@iann29/rastro 0.1.0-alpha.5 → 0.1.0-alpha.7

package/src/component/reports.ts

@@ -24,7 +24,9 @@ import {
   MAX_REPORT_BUCKETS,
   MAX_REPORT_RANGE_DAYS,
   MAX_REPORT_SITES,
+  MAX_VITALS_REPORT_ROWS,
   REPORT_ROLLUP_SHARDS,
+  VITALS_REPORT_PAGE_LIMIT,
 } from "./constants.js";
 import {
   createVisitorSketch,
@@ -48,8 +50,17 @@ import {
   funnelFieldsValidator,
   goalFieldsValidator,
   sessionFieldsValidator,
+  vitalMetricValidator,
 } from "./validators.js";
 import { resolveVisitorIdentities } from "./visitors.js";
+import {
+  mergeVitalHistograms,
+  VITAL_ALL,
+  VITAL_METRICS,
+  vitalHistogramPercentile,
+  vitalRatingCounts,
+  type VitalMetric,
+} from "./vitals.js";
 
 const sessionDocumentValidator = sessionFieldsValidator.extend({
   _id: v.id("sessions"),
@@ -110,7 +121,9 @@ const metricTotalsValidator = v.object({
   conversions: v.number(),
   revenueCents: v.number(),
 });
-const timePointValidator = metricTotalsValidator.extend({ timestamp: v.number() });
+const timePointValidator = metricTotalsValidator.extend({
+  timestamp: v.number(),
+});
 const topItemValidator = v.object({
   value: v.string(),
   count: v.number(),
@@ -199,7 +212,8 @@ export const overview = query({
     const currencies = new Set<string>();
     for (const siteId of siteIds) {
       const site = await ctx.db.get("sites", siteId);
-      if (!site) fail("NOT_FOUND", "site not found", { siteId: String(siteId) });
+      if (!site)
+        fail("NOT_FOUND", "site not found", { siteId: String(siteId) });
       currencies.add(site.currency ?? "USD");
     }
     if (currencies.size !== 1) {
@@ -208,7 +222,11 @@ export const overview = query({
       });
     }
     const currency = [...currencies][0];
-    const { from, to } = validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
+    const { from, to } = validateRange(
+      args.from,
+      args.to,
+      MAX_REPORT_RANGE_DAYS,
+    );
     const interval = args.interval ?? (to - from <= DAY_MS ? "hour" : "day");
     if (interval === "hour" && to - from > DAY_MS) {
       fail("INVALID_ARGUMENT", "hourly reports are limited to 24 hours");
@@ -218,7 +236,8 @@ export const overview = query({
     const firstBucket = Math.floor(from / intervalMs) * intervalMs;
     const lastBucket = Math.floor(to / intervalMs) * intervalMs;
     const bucketCount = Math.floor((lastBucket - firstBucket) / intervalMs) + 1;
-    const perSiteLimit = bucketCount *
+    const perSiteLimit =
+      bucketCount *
       (interval === "hour" ? HOURLY_AGGREGATE_SHARDS : AGGREGATE_SHARDS);
     if (perSiteLimit * siteIds.length > MAX_OVERVIEW_AGGREGATE_ROWS) {
       fail(
@@ -233,10 +252,14 @@ export const overview = query({
     let mergedVisitorSketch = visitorSketch;
     const pointVisitorSketches = new Map<number, VisitorSketch>();
     let visitorsComplete = true;
-    const dimensions = new Map<string, { value: string; count: number; revenueCents: number }>();
-    const overviewDataset = interval === "hour"
-      ? "overviewHour" as const
-      : "overviewDay" as const;
+    const dimensions = new Map<
+      string,
+      { value: string; count: number; revenueCents: number }
+    >();
+    const overviewDataset =
+      interval === "hour"
+        ? ("overviewHour" as const)
+        : ("overviewDay" as const);
 
     await assertSourceAvailable(ctx, siteIds, [overviewDataset], from);
 
@@ -291,7 +314,10 @@ export const overview = query({
       [...dimensions.entries()]
         .filter(([key]) => key.startsWith(`${type}:`))
         .map(([, value]) => value)
-        .sort((left, right) => right.count - left.count || left.value.localeCompare(right.value))
+        .sort(
+          (left, right) =>
+            right.count - left.count || left.value.localeCompare(right.value),
+        )
         .slice(0, 10);
     if (visitorsComplete) {
       totals.visitors = estimateVisitors(mergedVisitorSketch);
@@ -365,8 +391,15 @@ export const liveVisitors = query({
   handler: async (ctx, args) => {
     const siteIds = validateSiteIds(args.siteIds);
     const limit = args.limit ?? 100;
-    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIVE_VISITORS) {
-      fail("INVALID_ARGUMENT", `limit must be an integer between 1 and ${MAX_LIVE_VISITORS}`);
+    if (
+      !Number.isSafeInteger(limit) ||
+      limit < 1 ||
+      limit > MAX_LIVE_VISITORS
+    ) {
+      fail(
+        "INVALID_ARGUMENT",
+        `limit must be an integer between 1 and ${MAX_LIVE_VISITORS}`,
+      );
     }
     if (!Number.isFinite(args.now) || args.now < 0) {
       fail("INVALID_ARGUMENT", "now must be a positive timestamp");
@@ -593,22 +626,34 @@ export const visitorJourney = query({
     validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
     await assertSourceAvailable(ctx, siteIds, ["events"], args.from);
     const limit = args.limit ?? 200;
-    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_JOURNEY_EVENTS) {
-      fail("INVALID_ARGUMENT", `limit must be an integer between 1 and ${MAX_JOURNEY_EVENTS}`);
+    if (
+      !Number.isSafeInteger(limit) ||
+      limit < 1 ||
+      limit > MAX_JOURNEY_EVENTS
+    ) {
+      fail(
+        "INVALID_ARGUMENT",
+        `limit must be an integer between 1 and ${MAX_JOURNEY_EVENTS}`,
+      );
     }
     const rows: RawJourneyEvent[] = [];
     for (const siteId of siteIds) {
-      for (const visitorId of await resolveVisitorIdentities(ctx, siteId, args.visitorId)) {
-        const cutoff = rows.length >= limit
-          ? rows[limit - 1]!.timestamp
-          : args.to;
-        rows.push(...await loadVisitorJourneyEvents(ctx, {
-          siteId,
-          visitorId,
-          from: args.from,
-          to: cutoff,
-          resultLimit: limit,
-        }));
+      for (const visitorId of await resolveVisitorIdentities(
+        ctx,
+        siteId,
+        args.visitorId,
+      )) {
+        const cutoff =
+          rows.length >= limit ? rows[limit - 1]!.timestamp : args.to;
+        rows.push(
+          ...(await loadVisitorJourneyEvents(ctx, {
+            siteId,
+            visitorId,
+            from: args.from,
+            to: cutoff,
+            resultLimit: limit,
+          })),
+        );
         rows.sort(compareJourneyEvents);
         if (rows.length > limit) rows.length = limit;
       }
@@ -639,7 +684,10 @@ export const goalsReport = query({
       .take(MAX_GOALS_PER_SITE + 1);
     failIfIncomplete(goalRows, MAX_GOALS_PER_SITE, "goal definitions");
     const goals = goalRows;
-    const totals = new Map<string, { completions: number; valueCents: number }>();
+    const totals = new Map<
+      string,
+      { completions: number; valueCents: number }
+    >();
     const useRollups = await dailyRollupsAvailable(
       ctx,
       args.siteId,
@@ -696,12 +744,18 @@ export const goalsReport = query({
       })),
       truncated: false,
       metadata: {
-        basis: rollups ? "dailyRollup" as const : "boundedLegacy" as const,
-        coverage: await coverageForRange(ctx, [args.siteId], args.from, args.to, {
-          datasets: [rollups ? "goalRollups" : "goalCompletions"],
-          complete: true,
-          generation: rollups ? 1 : null,
-        }),
+        basis: rollups ? ("dailyRollup" as const) : ("boundedLegacy" as const),
+        coverage: await coverageForRange(
+          ctx,
+          [args.siteId],
+          args.from,
+          args.to,
+          {
+            datasets: [rollups ? "goalRollups" : "goalCompletions"],
+            complete: true,
+            generation: rollups ? 1 : null,
+          },
+        ),
         range: rangeSemantics(args.from, args.to),
       },
     };
@@ -712,7 +766,12 @@ const funnelReportItemValidator = funnelFieldsValidator.extend({
   _id: v.id("funnels"),
   _creationTime: v.number(),
   stepsReport: v.array(
-    v.object({ step: v.number(), name: v.string(), entrants: v.number(), completions: v.number() }),
+    v.object({
+      step: v.number(),
+      name: v.string(),
+      entrants: v.number(),
+      completions: v.number(),
+    }),
   ),
   truncated: v.boolean(),
   metadata: reportMetadataValidator,
@@ -802,7 +861,9 @@ export const funnelsReport = query({
         stepsReport,
         truncated: false,
         metadata: {
-          basis: rollups ? "dailyRollup" as const : "boundedLegacy" as const,
+          basis: rollups
+            ? ("dailyRollup" as const)
+            : ("boundedLegacy" as const),
           coverage: reportCoverage,
           range: rangeSemantics(args.from, args.to),
         },
@@ -842,7 +903,11 @@ export const affiliatesReport = query({
       .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
       .order("desc")
       .take(MAX_AFFILIATES_PER_SITE + 1);
-    failIfIncomplete(affiliateRows, MAX_AFFILIATES_PER_SITE, "affiliate definitions");
+    failIfIncomplete(
+      affiliateRows,
+      MAX_AFFILIATES_PER_SITE,
+      "affiliate definitions",
+    );
     const affiliates = affiliateRows;
     const useRollups = await dailyRollupsAvailable(
       ctx,
@@ -860,16 +925,22 @@ export const affiliatesReport = query({
           args.to,
         )
       : null;
-    const visits = new Map<string, {
-      visits: number;
-      visitors: Set<string>;
-      sketch: VisitorSketch;
-    }>();
-    const totals = new Map<string, {
-      conversions: number;
-      revenueCents: number;
-      commissionCents: number;
-    }>();
+    const visits = new Map<
+      string,
+      {
+        visits: number;
+        visitors: Set<string>;
+        sketch: VisitorSketch;
+      }
+    >();
+    const totals = new Map<
+      string,
+      {
+        conversions: number;
+        revenueCents: number;
+        commissionCents: number;
+      }
+    >();
     if (rollups) {
       for (const row of rollups) {
         const key = String(row.affiliateId);
@@ -960,22 +1031,30 @@ export const affiliatesReport = query({
           visits: traffic?.visits ?? 0,
           uniqueVisitors: rollups
             ? estimateVisitors(traffic?.sketch ?? createVisitorSketch())
-            : traffic?.visitors.size ?? 0,
+            : (traffic?.visitors.size ?? 0),
         };
       }),
       truncated: false,
       metadata: {
-        basis: rollups ? "dailyRollup" as const : "boundedLegacy" as const,
-        coverage: await coverageForRange(ctx, [args.siteId], args.from, args.to, {
-          datasets: rollups
-            ? ["affiliateRollups"]
-            : ["affiliateStats", "sessions"],
-          complete: true,
-          generation: rollups ? 1 : null,
-        }),
+        basis: rollups ? ("dailyRollup" as const) : ("boundedLegacy" as const),
+        coverage: await coverageForRange(
+          ctx,
+          [args.siteId],
+          args.from,
+          args.to,
+          {
+            datasets: rollups
+              ? ["affiliateRollups"]
+              : ["affiliateStats", "sessions"],
+            complete: true,
+            generation: rollups ? 1 : null,
+          },
+        ),
         range: rangeSemantics(args.from, args.to),
         uniqueVisitors: {
-          basis: rollups ? "estimatedUnique" as const : "exactLegacy" as const,
+          basis: rollups
+            ? ("estimatedUnique" as const)
+            : ("exactLegacy" as const),
           exact: !rollups,
         },
       },
@@ -983,6 +1062,153 @@ export const affiliatesReport = query({
   },
 });
 
+const vitalStatsValidator = v.object({
+  count: v.number(),
+  p75: v.number(),
+  average: v.number(),
+  good: v.number(),
+  needsImprovement: v.number(),
+  poor: v.number(),
+});
+
+export const vitalsReport = query({
+  args: { siteId: v.id("sites"), from: v.number(), to: v.number() },
+  returns: v.object({
+    metrics: v.array(
+      vitalStatsValidator.extend({
+        metric: vitalMetricValidator,
+        devices: v.array(vitalStatsValidator.extend({ device: v.string() })),
+        pages: v.array(vitalStatsValidator.extend({ page: v.string() })),
+        timeSeries: v.array(
+          v.object({
+            timestamp: v.number(),
+            count: v.number(),
+            p75: v.number(),
+          }),
+        ),
+      }),
+    ),
+    truncated: v.boolean(),
+    metadata: reportMetadataValidator,
+  }),
+  handler: async (ctx, args) => {
+    validateRange(args.from, args.to, MAX_FEATURE_ROLLUP_DAYS);
+    requireAlignedRange(args.from, args.to, DAY_MS, "vitals report");
+    await assertSourceAvailable(
+      ctx,
+      [args.siteId],
+      ["vitalRollups"],
+      args.from,
+    );
+    const rows = await ctx.db
+      .query("vitalRollups")
+      .withIndex("by_siteId_and_bucketStart", (range) =>
+        range
+          .eq("siteId", args.siteId)
+          .gte("bucketStart", args.from)
+          .lte("bucketStart", args.to),
+      )
+      .take(MAX_VITALS_REPORT_ROWS + 1);
+    failIfIncomplete(rows, MAX_VITALS_REPORT_ROWS, "vital rollups");
+
+    type Accumulated = { count: number; sum: number; histogram: number[] };
+    const fold = <Key>(
+      groups: Map<VitalMetric, Map<Key, Accumulated>>,
+      metric: VitalMetric,
+      key: Key,
+      entry: { count: number; sum: number; histogram: number[] },
+    ) => {
+      const group = groups.get(metric) ?? new Map<Key, Accumulated>();
+      const current = group.get(key) ?? { count: 0, sum: 0, histogram: [] };
+      current.count += entry.count;
+      current.sum += entry.sum;
+      current.histogram = mergeVitalHistograms(
+        current.histogram,
+        entry.histogram,
+      );
+      group.set(key, current);
+      groups.set(metric, group);
+    };
+    const byDevice = new Map<VitalMetric, Map<string, Accumulated>>();
+    const byPage = new Map<VitalMetric, Map<string, Accumulated>>();
+    const byDay = new Map<VitalMetric, Map<number, Accumulated>>();
+    for (const row of rows) {
+      for (const entry of row.metrics) {
+        if (row.page === VITAL_ALL) {
+          // A device row carries the complete signal once, so overall totals
+          // and the time series derive from this family alone.
+          fold(byDevice, entry.metric, row.device, entry);
+          fold(byDay, entry.metric, row.bucketStart, entry);
+        } else {
+          fold(byPage, entry.metric, row.page, entry);
+        }
+      }
+    }
+    const stats = (metric: VitalMetric, accumulated: Accumulated) => ({
+      count: accumulated.count,
+      p75: vitalHistogramPercentile(accumulated.histogram, 0.75),
+      average:
+        accumulated.count > 0
+          ? Math.round(accumulated.sum / accumulated.count)
+          : 0,
+      ...vitalRatingCounts(accumulated.histogram, metric),
+    });
+    const metrics = VITAL_METRICS.map((metric) => {
+      const overall: Accumulated = { count: 0, sum: 0, histogram: [] };
+      for (const accumulated of byDevice.get(metric)?.values() ?? []) {
+        overall.count += accumulated.count;
+        overall.sum += accumulated.sum;
+        overall.histogram = mergeVitalHistograms(
+          overall.histogram,
+          accumulated.histogram,
+        );
+      }
+      return {
+        metric,
+        ...stats(metric, overall),
+        devices: [...(byDevice.get(metric) ?? [])]
+          .map(([device, accumulated]) => ({
+            device,
+            ...stats(metric, accumulated),
+          }))
+          .sort((left, right) => right.count - left.count),
+        pages: [...(byPage.get(metric) ?? [])]
+          .map(([page, accumulated]) => ({
+            page,
+            ...stats(metric, accumulated),
+          }))
+          .sort(
+            (left, right) =>
+              right.count - left.count || left.page.localeCompare(right.page),
+          )
+          .slice(0, VITALS_REPORT_PAGE_LIMIT),
+        timeSeries: [...(byDay.get(metric) ?? [])]
+          .sort(([left], [right]) => left - right)
+          .map(([timestamp, accumulated]) => ({
+            timestamp,
+            count: accumulated.count,
+            p75: vitalHistogramPercentile(accumulated.histogram, 0.75),
+          })),
+      };
+    });
+    return {
+      metrics,
+      truncated: false,
+      metadata: {
+        basis: "dailyRollup" as const,
+        coverage: await coverageForRange(
+          ctx,
+          [args.siteId],
+          args.from,
+          args.to,
+          { datasets: ["vitalRollups"], complete: true },
+        ),
+        range: rangeSemantics(args.from, args.to),
+      },
+    };
+  },
+});
+
 const coverageDatasetValidator = v.union(
   v.literal("overviewHour"),
   v.literal("overviewDay"),
@@ -992,6 +1218,7 @@ const coverageDatasetValidator = v.union(
   v.literal("goals"),
   v.literal("funnels"),
   v.literal("affiliates"),
+  v.literal("vitals"),
 );
 
 export const dataCoverage = query({
@@ -1004,10 +1231,12 @@ export const dataCoverage = query({
     siteId: v.id("sites"),
     from: v.number(),
     to: v.number(),
-    datasets: v.array(v.object({
-      dataset: coverageDatasetValidator,
-      coverage: resultCoverageValidator,
-    })),
+    datasets: v.array(
+      v.object({
+        dataset: coverageDatasetValidator,
+        coverage: resultCoverageValidator,
+      }),
+    ),
   }),
   handler: async (ctx, args) => {
     validateRange(args.from, args.to, MAX_REPORT_RANGE_DAYS);
@@ -1020,21 +1249,24 @@ export const dataCoverage = query({
       "goals",
       "funnels",
       "affiliates",
+      "vitals",
     ] as const;
     return {
       siteId: args.siteId,
       from: args.from,
       to: args.to,
-      datasets: await Promise.all(datasets.map(async (dataset) => ({
-        dataset,
-        coverage: await datasetCoverageForRange(
-          ctx,
-          args.siteId,
+      datasets: await Promise.all(
+        datasets.map(async (dataset) => ({
           dataset,
-          args.from,
-          args.to,
-        ),
-      }))),
+          coverage: await datasetCoverageForRange(
+            ctx,
+            args.siteId,
+            dataset,
+            args.from,
+            args.to,
+          ),
+        })),
+      ),
     };
   },
 });
@@ -1144,7 +1376,11 @@ async function loadAffiliateDailyRollups(
           .lte("bucketStart", to),
       )
       .take(perAffiliateLimit + 1);
-    failIfIncomplete(affiliateRows, perAffiliateLimit, "affiliate daily rollups");
+    failIfIncomplete(
+      affiliateRows,
+      perAffiliateLimit,
+      "affiliate daily rollups",
+    );
     rows.push(...affiliateRows);
     await requireFeatureReadHeadroom(ctx, "affiliate daily rollups");
   }
@@ -1172,20 +1408,28 @@ async function requireFeatureReadHeadroom(ctx: QueryCtx, dataset: string) {
     metrics.bytesRead.remaining < FEATURE_REPORT_BYTE_RESERVE ||
     metrics.documentsRead.remaining < FEATURE_REPORT_DOCUMENT_RESERVE
   ) {
-    fail("REPORT_INCOMPLETE", `${dataset} exceeds its byte or document budget`, {
-      dataset,
-      bytesRead: metrics.bytesRead.used,
-      documentsRead: metrics.documentsRead.used,
-    });
+    fail(
+      "REPORT_INCOMPLETE",
+      `${dataset} exceeds its byte or document budget`,
+      {
+        dataset,
+        bytesRead: metrics.bytesRead.used,
+        documentsRead: metrics.documentsRead.used,
+      },
+    );
   }
 }
 
 function failIfIncomplete<T>(rows: T[], maximum: number, dataset: string) {
   if (rows.length > maximum) {
-    fail("REPORT_INCOMPLETE", `${dataset} exceeds the complete report read budget`, {
-      maximumRows: maximum,
-      dataset,
-    });
+    fail(
+      "REPORT_INCOMPLETE",
+      `${dataset} exceeds the complete report read budget`,
+      {
+        maximumRows: maximum,
+        dataset,
+      },
+    );
   }
 }
 
@@ -1200,45 +1444,52 @@ async function coverageForRange(
     generation?: 1 | null;
   },
 ) {
-  const controls = await Promise.all(siteIds.map((siteId) =>
-    ctx.db
-      .query("analyticsCoverage")
-      .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
-      .unique()
-  ));
-  const sourceRanges = await Promise.all(siteIds.map((siteId) =>
-    sourceSetRange(ctx, siteId, options.datasets)
-  ));
+  const controls = await Promise.all(
+    siteIds.map((siteId) =>
+      ctx.db
+        .query("analyticsCoverage")
+        .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
+        .unique(),
+    ),
+  );
+  const sourceRanges = await Promise.all(
+    siteIds.map((siteId) => sourceSetRange(ctx, siteId, options.datasets)),
+  );
   const retainedBefore = controls.reduce<number | null>((latest, control) => {
     const before = control?.retained
-      .filter((item) => options.datasets.some((dataset) => dataset === item.dataset))
+      .filter((item) =>
+        options.datasets.some((dataset) => dataset === item.dataset),
+      )
       .reduce<number | undefined>(
         (latest, item) => Math.max(latest ?? 0, item.before),
         undefined,
       );
     return before === undefined ? latest : Math.max(latest ?? 0, before);
   }, null);
-  const availableFrom = options.generation === 1
-    ? controls.length > 0 && controls.every(Boolean)
-      ? Math.max(...controls.map((control) => control!.rollupCompleteFrom))
-      : null
-    : sourceRanges.length > 0 && sourceRanges.every(Boolean)
-      ? Math.max(...sourceRanges.map((range) => range!.from))
+  const availableFrom =
+    options.generation === 1
+      ? controls.length > 0 && controls.every(Boolean)
+        ? Math.max(...controls.map((control) => control!.rollupCompleteFrom))
+        : null
+      : sourceRanges.length > 0 && sourceRanges.every(Boolean)
+        ? Math.max(...sourceRanges.map((range) => range!.from))
+        : null;
+  const availableThrough =
+    sourceRanges.length > 0 && sourceRanges.every(Boolean)
+      ? Math.min(...sourceRanges.map((range) => range!.through))
       : null;
-  const availableThrough = sourceRanges.length > 0 && sourceRanges.every(Boolean)
-    ? Math.min(...sourceRanges.map((range) => range!.through))
-    : null;
   let state: "complete" | "partial" | "retained" | "unavailable";
   if (retainedBefore !== null && to < retainedBefore) {
     state = "unavailable";
   } else if (retainedBefore !== null && from < retainedBefore) {
     state = "partial";
-  } else if (options.complete || (
-    availableFrom !== null &&
-    availableThrough !== null &&
-    from >= availableFrom &&
-    to <= availableThrough
-  )) {
+  } else if (
+    options.complete ||
+    (availableFrom !== null &&
+      availableThrough !== null &&
+      from >= availableFrom &&
+      to <= availableThrough)
+  ) {
     state = "complete";
   } else if (sourceRanges.some(Boolean)) {
     state = "retained";
@@ -1260,12 +1511,14 @@ async function assertSourceAvailable(
   sources: CoverageSource[],
   from: number,
 ) {
-  const rows = await Promise.all(siteIds.map((siteId) =>
-    ctx.db
-      .query("analyticsCoverage")
-      .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
-      .unique()
-  ));
+  const rows = await Promise.all(
+    siteIds.map((siteId) =>
+      ctx.db
+        .query("analyticsCoverage")
+        .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
+        .unique(),
+    ),
+  );
   const cutoff = rows.reduce<number | null>((latest, row) => {
     for (const retained of row?.retained ?? []) {
       if (sources.some((source) => source === retained.dataset)) {
@@ -1275,9 +1528,13 @@ async function assertSourceAvailable(
     return latest;
   }, null);
   if (cutoff !== null && from < cutoff) {
-    fail("REPORT_INCOMPLETE", "requested report range intersects retained data", {
-      retainedBefore: cutoff,
-    });
+    fail(
+      "REPORT_INCOMPLETE",
+      "requested report range intersects retained data",
+      {
+        retainedBefore: cutoff,
+      },
+    );
   }
 }
 
@@ -1288,31 +1545,42 @@ async function datasetCoverageForRange(
   from: number,
   to: number,
 ) {
-  const sourceOptions: CoverageSource[][] = dataset === "goals"
-    ? [["goalRollups"], ["goalCompletions"]]
-    : dataset === "funnels"
-      ? [["funnelRollups"], ["funnelSteps"]]
-      : dataset === "affiliates"
-        ? [["affiliateRollups"], ["affiliateStats", "sessions"]]
-        : [[dataset]];
-  const options = (await Promise.all(sourceOptions.map(async (sources) => {
-    const rollupDataset = sources[0] as
-      | "goalRollups"
-      | "funnelRollups"
-      | "affiliateRollups";
-    const isRollup = rollupDataset.endsWith("Rollups");
-    const complete = isRollup
-      ? await dailyRollupsAvailable(ctx, siteId, from, to, rollupDataset)
-      : false;
-    if (isRollup && !complete) return null;
+  // Vitals have no legacy fallback source; the rollup either covers the range
+  // or the coverage states say how much of it exists.
+  if (dataset === "vitals") {
     return coverageForRange(ctx, [siteId], from, to, {
-      datasets: sources,
-      complete,
-      generation: complete ? 1 : null,
+      datasets: ["vitalRollups"],
+      complete: false,
     });
-  }))).filter((option): option is NonNullable<typeof option> => option !== null);
-  return options.sort((left, right) =>
-    coverageRank(right.state) - coverageRank(left.state)
+  }
+  const sourceOptions: CoverageSource[][] =
+    dataset === "goals"
+      ? [["goalRollups"], ["goalCompletions"]]
+      : dataset === "funnels"
+        ? [["funnelRollups"], ["funnelSteps"]]
+        : dataset === "affiliates"
+          ? [["affiliateRollups"], ["affiliateStats", "sessions"]]
+          : [[dataset]];
+  const options = (
+    await Promise.all(
+      sourceOptions.map(async (sources) => {
+        const rollupDataset = sources[0] as
+          "goalRollups" | "funnelRollups" | "affiliateRollups";
+        const isRollup = rollupDataset.endsWith("Rollups");
+        const complete = isRollup
+          ? await dailyRollupsAvailable(ctx, siteId, from, to, rollupDataset)
+          : false;
+        if (isRollup && !complete) return null;
+        return coverageForRange(ctx, [siteId], from, to, {
+          datasets: sources,
+          complete,
+          generation: complete ? 1 : null,
+        });
+      }),
+    )
+  ).filter((option): option is NonNullable<typeof option> => option !== null);
+  return options.sort(
+    (left, right) => coverageRank(right.state) - coverageRank(left.state),
   )[0]!;
 }
 
@@ -1324,7 +1592,8 @@ type PublicCoverageDataset =
   | "conversions"
   | "goals"
   | "funnels"
-  | "affiliates";
+  | "affiliates"
+  | "vitals";
 
 type CoverageSource =
   | "overviewHour"
@@ -1337,7 +1606,8 @@ type CoverageSource =
   | "affiliateStats"
   | "goalRollups"
   | "funnelRollups"
-  | "affiliateRollups";
+  | "affiliateRollups"
+  | "vitalRollups";
 
 type SourceRange = { from: number; through: number };
 
@@ -1346,9 +1616,9 @@ async function sourceSetRange(
   siteId: Id<"sites">,
   sources: CoverageSource[],
 ): Promise<SourceRange | null> {
-  const ranges = (await Promise.all(
-    sources.map((source) => sourceRange(ctx, siteId, source)),
-  )).filter((range): range is SourceRange => range !== null);
+  const ranges = (
+    await Promise.all(sources.map((source) => sourceRange(ctx, siteId, source)))
+  ).filter((range): range is SourceRange => range !== null);
   if (ranges.length === 0) return null;
   return {
     from: Math.min(...ranges.map((range) => range.from)),
@@ -1362,79 +1632,129 @@ async function sourceRange(
   source: CoverageSource,
 ): Promise<SourceRange | null> {
   if (source === "overviewHour" || source === "overviewDay") {
-    const granularity = source === "overviewHour" ? "hour" as const : "day" as const;
+    const granularity =
+      source === "overviewHour" ? ("hour" as const) : ("day" as const);
     const [first, last] = await Promise.all([
-      ctx.db.query("aggregateBuckets")
+      ctx.db
+        .query("aggregateBuckets")
         .withIndex("by_siteId_and_granularity_and_bucketStart", (range) =>
           range.eq("siteId", siteId).eq("granularity", granularity),
-        ).order("asc").take(1),
-      ctx.db.query("aggregateBuckets")
+        )
+        .order("asc")
+        .take(1),
+      ctx.db
+        .query("aggregateBuckets")
         .withIndex("by_siteId_and_granularity_and_bucketStart", (range) =>
           range.eq("siteId", siteId).eq("granularity", granularity),
-        ).order("desc").take(1),
+        )
+        .order("desc")
+        .take(1),
     ]);
     return bounds(first[0]?.bucketStart, last[0]?.bucketStart);
   }
   if (source === "events") {
     const [first, last] = await Promise.all([
-      ctx.db.query("eventBatches")
-        .withIndex("by_siteId_and_bucketStart", (range) => range.eq("siteId", siteId))
-        .order("asc").take(1),
-      ctx.db.query("eventBatches")
-        .withIndex("by_siteId_and_bucketStart", (range) => range.eq("siteId", siteId))
-        .order("desc").take(1),
+      ctx.db
+        .query("eventBatches")
+        .withIndex("by_siteId_and_bucketStart", (range) =>
+          range.eq("siteId", siteId),
+        )
+        .order("asc")
+        .take(1),
+      ctx.db
+        .query("eventBatches")
+        .withIndex("by_siteId_and_bucketStart", (range) =>
+          range.eq("siteId", siteId),
+        )
+        .order("desc")
+        .take(1),
     ]);
     return bounds(first[0]?.bucketStart, last[0]?.bucketStart);
   }
   if (source === "sessions") {
     const [first, last] = await Promise.all([
-      ctx.db.query("sessions")
-        .withIndex("by_siteId_and_startedAt", (range) => range.eq("siteId", siteId))
-        .order("asc").take(1),
-      ctx.db.query("sessions")
-        .withIndex("by_siteId_and_lastSeenAt", (range) => range.eq("siteId", siteId))
-        .order("desc").take(1),
+      ctx.db
+        .query("sessions")
+        .withIndex("by_siteId_and_startedAt", (range) =>
+          range.eq("siteId", siteId),
+        )
+        .order("asc")
+        .take(1),
+      ctx.db
+        .query("sessions")
+        .withIndex("by_siteId_and_lastSeenAt", (range) =>
+          range.eq("siteId", siteId),
+        )
+        .order("desc")
+        .take(1),
     ]);
     return bounds(first[0]?.startedAt, last[0]?.lastSeenAt);
   }
   if (source === "conversions") {
     const [first, last] = await Promise.all([
-      ctx.db.query("conversions")
-        .withIndex("by_siteId_and_timestamp", (range) => range.eq("siteId", siteId))
-        .order("asc").take(1),
-      ctx.db.query("conversions")
-        .withIndex("by_siteId_and_timestamp", (range) => range.eq("siteId", siteId))
-        .order("desc").take(1),
+      ctx.db
+        .query("conversions")
+        .withIndex("by_siteId_and_timestamp", (range) =>
+          range.eq("siteId", siteId),
+        )
+        .order("asc")
+        .take(1),
+      ctx.db
+        .query("conversions")
+        .withIndex("by_siteId_and_timestamp", (range) =>
+          range.eq("siteId", siteId),
+        )
+        .order("desc")
+        .take(1),
     ]);
     return bounds(first[0]?.timestamp, last[0]?.timestamp);
   }
   if (source === "goalCompletions") {
     const [first, last] = await Promise.all([
-      ctx.db.query("goalCompletions")
-        .withIndex("by_siteId_and_timestamp", (range) => range.eq("siteId", siteId))
-        .order("asc").take(1),
-      ctx.db.query("goalCompletions")
-        .withIndex("by_siteId_and_timestamp", (range) => range.eq("siteId", siteId))
-        .order("desc").take(1),
+      ctx.db
+        .query("goalCompletions")
+        .withIndex("by_siteId_and_timestamp", (range) =>
+          range.eq("siteId", siteId),
+        )
+        .order("asc")
+        .take(1),
+      ctx.db
+        .query("goalCompletions")
+        .withIndex("by_siteId_and_timestamp", (range) =>
+          range.eq("siteId", siteId),
+        )
+        .order("desc")
+        .take(1),
     ]);
     return bounds(first[0]?.timestamp, last[0]?.timestamp);
   }
-  const table = source === "funnelSteps"
-    ? "funnelStepBuckets" as const
-    : source === "affiliateStats"
-      ? "affiliateDailyStats" as const
-      : source === "goalRollups"
-        ? "goalDailyRollups" as const
-        : source === "funnelRollups"
-          ? "funnelDailyRollups" as const
-          : "affiliateDailyRollups" as const;
+  const table =
+    source === "funnelSteps"
+      ? ("funnelStepBuckets" as const)
+      : source === "affiliateStats"
+        ? ("affiliateDailyStats" as const)
+        : source === "goalRollups"
+          ? ("goalDailyRollups" as const)
+          : source === "funnelRollups"
+            ? ("funnelDailyRollups" as const)
+            : source === "vitalRollups"
+              ? ("vitalRollups" as const)
+              : ("affiliateDailyRollups" as const);
   const [first, last] = await Promise.all([
-    ctx.db.query(table)
-      .withIndex("by_siteId_and_bucketStart", (range) => range.eq("siteId", siteId))
-      .order("asc").take(1),
-    ctx.db.query(table)
-      .withIndex("by_siteId_and_bucketStart", (range) => range.eq("siteId", siteId))
-      .order("desc").take(1),
+    ctx.db
+      .query(table)
+      .withIndex("by_siteId_and_bucketStart", (range) =>
+        range.eq("siteId", siteId),
+      )
+      .order("asc")
+      .take(1),
+    ctx.db
+      .query(table)
+      .withIndex("by_siteId_and_bucketStart", (range) =>
+        range.eq("siteId", siteId),
+      )
+      .order("desc")
+      .take(1),
   ]);
   return bounds(first[0]?.bucketStart, last[0]?.bucketStart);
 }
@@ -1443,14 +1763,15 @@ function bounds(from: number | undefined, through: number | undefined) {
   return from === undefined || through === undefined ? null : { from, through };
 }
 
-function coverageRank(state: "complete" | "partial" | "retained" | "unavailable") {
+function coverageRank(
+  state: "complete" | "partial" | "retained" | "unavailable",
+) {
   if (state === "complete") return 3;
   if (state === "retained") return 2;
   if (state === "partial") return 1;
   return 0;
 }
 
-
 type MetricTotals = {
   events: number;
   pageviews: number;
@@ -1491,8 +1812,15 @@ function addMetrics(target: MetricTotals, source: MetricTotals) {
 
 function validateSiteIds<T>(siteIds: T[]): T[] {
   const unique = [...new Set(siteIds)];
-  if (unique.length < 1 || unique.length > MAX_REPORT_SITES || unique.length !== siteIds.length) {
-    fail("INVALID_ARGUMENT", `siteIds must contain 1-${MAX_REPORT_SITES} unique IDs`);
+  if (
+    unique.length < 1 ||
+    unique.length > MAX_REPORT_SITES ||
+    unique.length !== siteIds.length
+  ) {
+    fail(
+      "INVALID_ARGUMENT",
+      `siteIds must contain 1-${MAX_REPORT_SITES} unique IDs`,
+    );
   }
   return unique;
 }
@@ -1667,22 +1995,23 @@ function keysetPaginationResult<T>(
 ) {
   const page = rows.slice(0, pagination.numItems);
   const isDone = rows.length <= pagination.numItems;
-  const next = page.length > 0
-    ? cursorFor(page[page.length - 1])
-    : pagination.cursor;
+  const next =
+    page.length > 0 ? cursorFor(page[page.length - 1]) : pagination.cursor;
   return {
     page,
     isDone,
-    continueCursor: btoa(JSON.stringify({
-      v: 2,
-      k: pagination.scope.kind,
-      s: pagination.scope.siteId,
-      n: pagination.scope.sessionId ?? null,
-      f: pagination.scope.from,
-      t: pagination.scope.to,
-      x: next?.timestamp ?? pagination.scope.to,
-      c: next?.creationTime ?? Number.MAX_SAFE_INTEGER,
-    })),
+    continueCursor: btoa(
+      JSON.stringify({
+        v: 2,
+        k: pagination.scope.kind,
+        s: pagination.scope.siteId,
+        n: pagination.scope.sessionId ?? null,
+        f: pagination.scope.from,
+        t: pagination.scope.to,
+        x: next?.timestamp ?? pagination.scope.to,
+        c: next?.creationTime ?? Number.MAX_SAFE_INTEGER,
+      }),
+    ),
   };
 }
 
@@ -1694,26 +2023,28 @@ function journeyPaginationResult(
   const isDone = rows.length <= pagination.numItems;
   const last = page.at(-1);
   const next = last
-      ? {
-          timestamp: last.timestamp,
-          creationTime: last._creationTime,
-          id: last._id,
+    ? {
+        timestamp: last.timestamp,
+        creationTime: last._creationTime,
+        id: last._id,
       }
     : pagination.cursor;
   return {
     page,
     isDone,
-    continueCursor: btoa(JSON.stringify({
-      v: 4,
-      k: pagination.scope.kind,
-      s: pagination.scope.siteId,
-      n: pagination.scope.sessionId,
-      f: pagination.scope.from,
-      t: pagination.scope.to,
-      x: next?.timestamp ?? pagination.scope.to,
-      c: next?.creationTime ?? Number.MAX_SAFE_INTEGER,
-      i: next?.id ?? "~",
-    })),
+    continueCursor: btoa(
+      JSON.stringify({
+        v: 4,
+        k: pagination.scope.kind,
+        s: pagination.scope.siteId,
+        n: pagination.scope.sessionId,
+        f: pagination.scope.from,
+        t: pagination.scope.to,
+        x: next?.timestamp ?? pagination.scope.to,
+        c: next?.creationTime ?? Number.MAX_SAFE_INTEGER,
+        i: next?.id ?? "~",
+      }),
+    ),
   };
 }
 
@@ -1722,8 +2053,15 @@ function validatePagination(options: {
   maximumRowsRead?: number;
   maximumBytesRead?: number;
 }) {
-  if (!Number.isSafeInteger(options.numItems) || options.numItems < 1 || options.numItems > 100) {
-    fail("INVALID_ARGUMENT", "pagination numItems must be an integer between 1 and 100");
+  if (
+    !Number.isSafeInteger(options.numItems) ||
+    options.numItems < 1 ||
+    options.numItems > 100
+  ) {
+    fail(
+      "INVALID_ARGUMENT",
+      "pagination numItems must be an integer between 1 and 100",
+    );
   }
   if (
     options.maximumRowsRead !== undefined &&
@@ -1731,7 +2069,10 @@ function validatePagination(options: {
       options.maximumRowsRead < 1 ||
       options.maximumRowsRead > 1_000)
   ) {
-    fail("INVALID_ARGUMENT", "maximumRowsRead must be an integer between 1 and 1000");
+    fail(
+      "INVALID_ARGUMENT",
+      "maximumRowsRead must be an integer between 1 and 1000",
+    );
   }
   if (
     options.maximumBytesRead !== undefined &&
@@ -1739,6 +2080,9 @@ function validatePagination(options: {
       options.maximumBytesRead < 1 ||
       options.maximumBytesRead > 8_000_000)
   ) {
-    fail("INVALID_ARGUMENT", "maximumBytesRead must be an integer between 1 and 8000000");
+    fail(
+      "INVALID_ARGUMENT",
+      "maximumBytesRead must be an integer between 1 and 8000000",
+    );
   }
 }