blogwright-analytics 0.4.0-beta.3 → 0.4.0-beta.4

package/dist/app/_app/version.json

@@ -1 +1 @@
-{"version":"1788238916385"}
+{"version":"1788644015180"}

package/dist/app/index.html

@@ -6,72 +6,76 @@
     <!-- A dashboard bound to loopback has no icon to serve; an empty data URL
          answers the browser's request without a round trip that would 404. -->
     <link rel="icon" href="data:," />
-    <link href="./_app/immutable/entry/start.Dbi2RtrK.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/D1DPCGav.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/D2BnX0Uk.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/B3vZDoek.js" rel="modulepreload">
-		<link href="./_app/immutable/entry/app.bmQ6qGMT.js" rel="modulepreload">
+    <link href="./_app/immutable/entry/start.Iz8smxW0.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/Cz3xtWLM.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DVCZGvXq.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DUJFqVVs.js" rel="modulepreload">
+		<link href="./_app/immutable/entry/app.w1HyN1Pe.js" rel="modulepreload">
 		<link href="./_app/immutable/chunks/HclGiUj8.js" rel="modulepreload">
 		<link href="./_app/immutable/chunks/xihTtKlq.js" rel="modulepreload">
-		<link href="./_app/immutable/nodes/0.UTMEigHJ.js" rel="modulepreload">
-		<link href="./_app/immutable/nodes/2.CQMIFodk.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/Bd1gDe3Y.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/Doz7YX1W.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/CyCGwyzf.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/ZvRY-WVy.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/DKMlMI4a.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/Dh958be7.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/CvyVA_jC.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/caXkbKD3.js" rel="modulepreload">
+		<link href="./_app/immutable/nodes/0.BjQeslHk.js" rel="modulepreload">
+		<link href="./_app/immutable/nodes/2.CByBWAMF.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DmKBckYv.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/BUku_rSO.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/D6rPBWFd.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/Y5urAfNy.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/Sb-KFJGv.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/xefVn_UF.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/BQHoVMm0.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/BAneOF1f.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DRQZHPoe.js" rel="modulepreload">
 		<link href="./_app/immutable/chunks/C58PZtCD.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/DJc8C0NK.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/CuOP1eLc.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/CAgm0Ruv.js" rel="modulepreload">
 		<link href="./_app/immutable/chunks/Db0q5_zr.js" rel="modulepreload">
 		<link href="./_app/immutable/chunks/CCch3uox.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/V9ZjaxiY.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C7qhOD3U.js" rel="modulepreload">
 		<link href="./_app/immutable/chunks/BID1NNRh.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/-aNGNaBT.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/BumHYZmq.js" rel="modulepreload">
 		<link href="./_app/immutable/chunks/RobXhXPM.js" rel="modulepreload">
 		<link href="./_app/immutable/chunks/Dfvzj6n2.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/xIq_fFFM.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/BZrG8lR6.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/DCkHk5n_.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/BC0iYSWx.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/BJngAqxk.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/B5KRA4hC.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/RBkNRIpl.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/D26njVw7.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/CSrT-PUe.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/Cr8mHXFf.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/C0tbX_qQ.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DodcabfQ.js" rel="modulepreload">
 		<link href="./_app/immutable/chunks/BR2LaRms.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/CRTcXoMo.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/vDgBJUjM.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/DMoYijy0.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/D0Ty6LN0.js" rel="modulepreload">
-		<link href="./_app/immutable/chunks/BnKf2MvA.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DnQEoGed.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/BpoiI2_d.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/CU11V7_a.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/B6Dt35mA.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/BoX17NrM.js" rel="modulepreload">
+		<link href="./_app/immutable/chunks/DoNmKjPy.js" rel="modulepreload">
 		
-		<link href="./_app/immutable/assets/0.BTQrrh5B.css" rel="stylesheet">
+		<link href="./_app/immutable/assets/0.BfwUqNJ-.css" rel="stylesheet">
 		<link href="./_app/immutable/assets/Group.DaJMILJc.css" rel="stylesheet">
-		<link href="./_app/immutable/assets/Text.j9l35qB0.css" rel="stylesheet">
 		<link href="./_app/immutable/assets/Path.CvpwNZ6g.css" rel="stylesheet">
+		<link href="./_app/immutable/assets/Text.j9l35qB0.css" rel="stylesheet">
+		<link href="./_app/immutable/assets/Tooltip.BsTJVNOF.css" rel="stylesheet">
 		<link href="./_app/immutable/assets/Rect.CtRaGMmQ.css" rel="stylesheet">
 		<link href="./_app/immutable/assets/Line.fkmsECm9.css" rel="stylesheet">
 		<link href="./_app/immutable/assets/Circle.C5MKzgk2.css" rel="stylesheet">
-		<link href="./_app/immutable/assets/2.DoCaRy3T.css" rel="stylesheet">
+		<link href="./_app/immutable/assets/2.lkfjnM1s.css" rel="stylesheet">
 		<link href="./_app/immutable/assets/Voronoi.ce7atosu.css" rel="stylesheet">
 		<link href="./_app/immutable/assets/ChartAnnotations.CPxIG7Mw.css" rel="stylesheet">
 		<link href="./_app/immutable/assets/Labels.BxZ4NUVz.css" rel="stylesheet">
 		<link href="./_app/immutable/assets/Legend.DTV5rk9m.css" rel="stylesheet">
-		<link href="./_app/immutable/assets/DefaultTooltip.BXd66MzC.css" rel="stylesheet">
+		<link href="./_app/immutable/assets/DefaultTooltip.CXdtNw-m.css" rel="stylesheet">
   </head>
   <body data-sveltekit-preload-data="tap">
     
 			<script>
 				{
-					__sveltekit_1447kmy = {
+					__sveltekit_uk2rko = {
 						base: new URL(".", location).pathname.slice(0, -1)
 					};
 
 					const element = document.currentScript.parentElement;
 
 					Promise.all([
-						import("./_app/immutable/entry/start.Dbi2RtrK.js"),
-						import("./_app/immutable/entry/app.bmQ6qGMT.js")
+						import("./_app/immutable/entry/start.Iz8smxW0.js"),
+						import("./_app/immutable/entry/app.w1HyN1Pe.js")
 					]).then(([kit, app]) => {
 						kit.start(app, element);
 					});

package/dist/nodes.js

@@ -2954,6 +2954,7 @@ export function analyticsLogDeliveryNode() {
             // missing destination each fail with nothing sent.
             const site = requireSiteDeliverySource(ctx);
             const destinationArn = requireLogDestinationArn(ctx);
+            const requestDay = utcDay(new Date());
             await logs(ctx).createDelivery(site.source, destinationArn, {
                 // `CLOUDFRONT_RECORD_FIELDS`, never a list restated here: `schema.ts`
                 // owns which CloudFront fields exist, which ones fill a column, and
@@ -2986,7 +2987,7 @@ export function analyticsLogDeliveryNode() {
             // {@link CREATED_DAY_KEY} for why moving it later is the one direction
             // that corrupts data rather than merely losing some.
             if (typeof out[CREATED_DAY_KEY] !== 'string')
-                out[CREATED_DAY_KEY] = utcDay(new Date());
+                out[CREATED_DAY_KEY] = requestDay;
         },
         async delete(ctx) {
             // This plugin's own deliveries and nothing else - **never

package/dist/path-filter.d.ts

@@ -0,0 +1,4 @@
+/** Shared validation for literal, segment-bounded path filters. */
+export declare function normalizePathFilter(value: unknown): string | undefined;
+/** User-facing validation shares the exact rules used by query preparation. */
+export declare function pathProblem(value: string): string | undefined;

package/dist/path-filter.js

@@ -0,0 +1,34 @@
+/** Shared validation for literal, segment-bounded path filters. */
+export function normalizePathFilter(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error('Path must be a string.');
+    const path = value.trim();
+    if (path === '')
+        return undefined;
+    // Reject ASCII control characters without embedding them in a regular expression.
+    const hasControlCharacter = Array.from(path).some((character) => {
+        const code = character.charCodeAt(0);
+        return code < 0x20 || code === 0x7f;
+    });
+    if (!path.startsWith('/') ||
+        path.startsWith('//') ||
+        /[\s?#\\]/.test(path) ||
+        hasControlCharacter) {
+        throw new Error('Enter a path starting with /, without a query string, fragment, or spaces.');
+    }
+    return path.replace(/\/+$/, '') || '/';
+}
+/** User-facing validation shares the exact rules used by query preparation. */
+export function pathProblem(value) {
+    try {
+        normalizePathFilter(value);
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return error.message;
+        throw error;
+    }
+}

package/dist/queries.d.ts

@@ -48,6 +48,7 @@
  * Pure data and pure functions only: no `node:` builtin, no vendor SDK, no
  * `fetch`. Nothing here runs a statement - that is `AnalyticsQuery`'s adapter.
  */
+import { type ViewGranularity } from './view-granularity.js';
 import type { AnalyticsConfig } from './config.js';
 import type { PageViewColumnName } from './schema.js';
 /**
@@ -74,16 +75,16 @@ export declare const PAGE_VIEWS_RELATION = "page_views";
  * all of them; the list is per-definition so a statement that forgot one is a
  * test failure naming that query rather than a filter that quietly never ran.
  */
-declare const QUERY_PARAM_NAMES: readonly ["from", "to", "include_bots"];
+declare const QUERY_PARAM_NAMES: readonly ["from", "to", "include_bots", "bucket_minutes", "from_time", "to_time"];
 /** One of {@link QUERY_PARAM_NAMES}. */
 type QueryParamName = (typeof QUERY_PARAM_NAMES)[number];
 /** A value bound to a placeholder. Days are bound as text and cast in the SQL. */
 type BindValue = string | boolean;
-/** An inclusive range of UTC days, each `YYYY-MM-DD` - the `day` partition's own form. */
+/** UTC calendar days (inclusive) or minute timestamps (start inclusive, end exclusive). */
 interface DateRange {
-    /** First day of the range, inclusive. */
+    /** Inclusive start day or UTC minute. */
     readonly from: string;
-    /** Last day of the range, inclusive. */
+    /** Inclusive end day, or exclusive end UTC minute. */
     readonly to: string;
 }
 /**
@@ -92,7 +93,13 @@ interface DateRange {
  * `config.analytics.bots` (task 44) through {@link BOTS_INCLUDED_BY_DEFAULT}.
  */
 export interface QueryParams {
-    /** The days to report over. */
+    /** Optional uppercase ISO country code. */
+    readonly country?: string | undefined;
+    /** Exact path and descendants at a slash boundary; blank means every path. */
+    readonly path?: string | undefined;
+    /** Include disjoint bot/non-bot contributions; requires bots to be included. */
+    readonly splitBots?: boolean | undefined;
+    /** The UTC reporting window. */
     readonly range: DateRange;
     /**
      * Whether bot-flagged rows are counted. Absent means "whatever
@@ -101,6 +108,8 @@ export interface QueryParams {
      * spec's Decision *Flag bots, do not drop them*.
      */
     readonly includeBots?: boolean | undefined;
+    /** UTC bucket width; accepted only by views-over-time. */
+    readonly granularity?: ViewGranularity | undefined;
 }
 /** One named query: its statement, what it reads, what it binds, what it returns. */
 interface QueryDefinition {
@@ -279,7 +288,7 @@ export declare function queryDefinition(name: string): QueryDefinition;
 export interface PreparedQuery {
     /** The name that resolved. */
     readonly name: QueryName;
-    /** The statement to execute, exactly as its definition carries it. */
+    /** The fixed statement to execute, including an intraday variant when requested. */
     readonly sql: string;
     /** The columns a row of the result carries. */
     readonly resultColumns: readonly string[];

package/dist/queries.js

@@ -48,6 +48,9 @@
  * Pure data and pure functions only: no `node:` builtin, no vendor SDK, no
  * `fetch`. Nothing here runs a statement - that is `AnalyticsQuery`'s adapter.
  */
+import { normalizePathFilter } from './path-filter.js';
+import { withTrafficBreakdown } from './traffic-breakdown.js';
+import { parseViewGranularity, VIEW_GRANULARITIES, } from './view-granularity.js';
 /**
  * The relation every named query reads. Not "the configured table name" - the
  * adapter binds this name to the configured `<namespace>.<table>` inside the
@@ -74,7 +77,14 @@ function sql(fragments, ...relations) {
  * all of them; the list is per-definition so a statement that forgot one is a
  * test failure naming that query rather than a filter that quietly never ran.
  */
-const QUERY_PARAM_NAMES = ['from', 'to', 'include_bots'];
+const QUERY_PARAM_NAMES = [
+    'from',
+    'to',
+    'include_bots',
+    'bucket_minutes',
+    'from_time',
+    'to_time',
+];
 /**
  * The `x-edge-result-type` values CloudFront reports for a cache hit. AWS
  * documents that field's values as `Hit`, `RefreshHit`, `Miss`,
@@ -333,6 +343,13 @@ function isCalendarDay(day) {
         return false;
     return new Date(time).toISOString().slice(0, DAY_LENGTH) === day;
 }
+/** Minute precision only; explicit UTC prevents host-timezone interpretation. */
+function isUtcMinute(value) {
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}Z$/.test(value))
+        return false;
+    const instant = Date.parse(value);
+    return Number.isFinite(instant) && new Date(instant).toISOString().slice(0, 16) + 'Z' === value;
+}
 /**
  * Resolve a name to its definition, raising with the available names when it
  * is not one of them. Takes a `string` rather than a {@link QueryName} because
@@ -368,18 +385,31 @@ export function queryDefinition(name) {
 function validateRange(name, range) {
     const from = range?.from;
     const to = range?.to;
-    if (typeof from !== 'string' || !isCalendarDay(from)) {
-        throw new Error(`analytics query ${describeValue(name)}: range.from must be a YYYY-MM-DD calendar day, got ${describeValue(from)}`);
+    if (typeof from !== 'string' || !(isCalendarDay(from) || isUtcMinute(from))) {
+        throw new Error(`analytics query ${describeValue(name)}: range.from must be a YYYY-MM-DD calendar day or YYYY-MM-DDTHH:mmZ UTC minute, got ${describeValue(from)}`);
+    }
+    if (typeof to !== 'string' || !(isCalendarDay(to) || isUtcMinute(to))) {
+        throw new Error(`analytics query ${describeValue(name)}: range.to must be a YYYY-MM-DD calendar day or YYYY-MM-DDTHH:mmZ UTC minute, got ${describeValue(to)}`);
     }
-    if (typeof to !== 'string' || !isCalendarDay(to)) {
-        throw new Error(`analytics query ${describeValue(name)}: range.to must be a YYYY-MM-DD calendar day, got ${describeValue(to)}`);
+    if (isUtcMinute(from) !== isUtcMinute(to)) {
+        throw new Error('range endpoints must both be calendar days or both UTC minute timestamps');
     }
-    // Both are `YYYY-MM-DD`, so lexical order is chronological order.
-    if (from > to) {
+    // Canonical UTC strings sort chronologically.
+    if (from > to || (isUtcMinute(from) && from === to)) {
         throw new Error(`analytics query ${describeValue(name)}: range is inverted - from ${describeValue(from)} is after to ${describeValue(to)}`);
     }
     return { from, to };
 }
+/** Intraday alternative keeps the day partition filter for Iceberg pruning. */
+const INTRADAY_VIEWS_SQL = sql `
+SELECT strftime(time_bucket(CAST($bucket_minutes AS BIGINT) * INTERVAL '1 minute', event_time), '%Y-%m-%dT%H:%M:%SZ') AS day,
+       count(*) AS views
+FROM ${PAGE_VIEWS}
+WHERE day BETWEEN CAST($from AS DATE) AND CAST($to AS DATE)
+  AND ($include_bots OR NOT coalesce(is_bot, false))
+GROUP BY 1
+ORDER BY 1
+`;
 /**
  * Resolve a name and its parameters into the statement and the bindings an
  * adapter runs - the one boundary where an unknown name and a bad range are
@@ -394,21 +424,61 @@ function validateRange(name, range) {
 export function prepareQuery(name, params, config) {
     const definition = queryDefinition(name);
     const range = validateRange(name, params.range);
+    const path = normalizePathFilter(params.path);
+    if (params.country !== undefined && !/^[A-Z]{2}$/.test(params.country)) {
+        throw new Error('country must be an uppercase two-letter country code');
+    }
+    if (params.granularity !== undefined && name !== 'views-over-time') {
+        throw new Error('granularity is only supported by views-over-time');
+    }
+    const granularity = parseViewGranularity(params.granularity);
+    const intraday = name === 'views-over-time' && granularity !== '24h';
     const includeBots = params.includeBots ?? BOTS_INCLUDED_BY_DEFAULT[config.bots];
+    if (params.splitBots !== undefined && typeof params.splitBots !== 'boolean') {
+        throw new Error('splitBots must be a boolean');
+    }
+    if (params.splitBots && !includeBots)
+        throw new Error('splitBots requires includeBots=true');
     const available = {
-        from: range.from,
-        to: range.to,
+        from: range.from.slice(0, 10),
+        to: range.to.slice(0, 10),
+        from_time: range.from,
+        to_time: range.to,
         include_bots: includeBots,
+        bucket_minutes: String(VIEW_GRANULARITIES[granularity].minutes),
     };
     const bindings = {};
     for (const bind of definition.binds)
         bindings[bind] = available[bind];
+    if (intraday)
+        bindings['bucket_minutes'] = available.bucket_minutes;
+    let statement = intraday ? INTRADAY_VIEWS_SQL : definition.sql;
+    if (isUtcMinute(range.from)) {
+        bindings['from_time'] = `${range.from.slice(0, 16)}:00Z`;
+        bindings['to_time'] = `${range.to.slice(0, 16)}:00Z`;
+        // Add a fixed predicate to the shared partition filter, including CTE queries.
+        statement = statement.replace('day BETWEEN CAST($from AS DATE) AND CAST($to AS DATE)', 'day BETWEEN CAST($from AS DATE) AND CAST($to AS DATE) AND event_time >= CAST($from_time AS TIMESTAMP) AND event_time < CAST($to_time AS TIMESTAMP)');
+    }
+    if (path !== undefined) {
+        bindings['path'] = path;
+        bindings['path_prefix'] = path === '/' ? '/' : `${path}/`;
+        // starts_with treats SQL wildcard characters as literal path characters.
+        statement = statement.replace('day BETWEEN CAST($from AS DATE) AND CAST($to AS DATE)', 'day BETWEEN CAST($from AS DATE) AND CAST($to AS DATE) AND (uri = $path OR starts_with(uri, $path_prefix))');
+    }
+    if (params.country !== undefined) {
+        bindings['country'] = params.country;
+        statement = statement.replace('day BETWEEN CAST($from AS DATE) AND CAST($to AS DATE)', 'day BETWEEN CAST($from AS DATE) AND CAST($to AS DATE) AND country = $country');
+    }
+    if (params.splitBots)
+        statement = withTrafficBreakdown(name, statement);
     return {
         // Justified by `queryDefinition` above: it raised unless `name` is one of
         // the table's own keys, which is exactly what `QueryName` enumerates.
         name: name,
-        sql: definition.sql,
-        resultColumns: definition.resultColumns,
+        sql: statement,
+        resultColumns: params.splitBots
+            ? [...definition.resultColumns, 'non_bot', 'bot']
+            : definition.resultColumns,
         bindings,
     };
 }

package/dist/reporting-range.d.ts

@@ -0,0 +1,53 @@
+/** UTC minute inputs and rolling reporting windows. */
+interface DateRange {
+    readonly from: string;
+    readonly to: string;
+}
+export declare const PERIODS: readonly [{
+    readonly value: "3h";
+    readonly label: "3H";
+    readonly hours: 3;
+}, {
+    readonly value: "6h";
+    readonly label: "6H";
+    readonly hours: 6;
+}, {
+    readonly value: "12h";
+    readonly label: "12H";
+    readonly hours: 12;
+}, {
+    readonly value: "24h";
+    readonly label: "24H";
+    readonly hours: 24;
+}, {
+    readonly value: "5d";
+    readonly label: "5D";
+    readonly hours: 120;
+}, {
+    readonly value: "1w";
+    readonly label: "1W";
+    readonly hours: 168;
+}, {
+    readonly value: "4w";
+    readonly label: "4W";
+    readonly hours: 672;
+}, {
+    readonly value: "3mo";
+    readonly label: "3M";
+    readonly months: 3;
+}, {
+    readonly value: "6mo";
+    readonly label: "6M";
+    readonly months: 6;
+}, {
+    readonly value: "1y";
+    readonly label: "1Y";
+    readonly months: 12;
+}];
+export type Period = (typeof PERIODS)[number]['value'];
+/** Input values intentionally omit a zone; the UI explicitly labels them UTC. */
+export declare function presetRange(period: Period, now?: Date): DateRange;
+/** Preserve the initial thirty-day window while allowing minute precision. */
+export declare function defaultRange(now?: Date): DateRange;
+export declare function rangeProblem(range: DateRange): string | undefined;
+export {};

package/dist/reporting-range.js

@@ -0,0 +1,57 @@
+const MINUTE_MS = 60_000;
+const DAY_MS = 86_400_000;
+export const PERIODS = [
+    { value: '3h', label: '3H', hours: 3 },
+    { value: '6h', label: '6H', hours: 6 },
+    { value: '12h', label: '12H', hours: 12 },
+    { value: '24h', label: '24H', hours: 24 },
+    { value: '5d', label: '5D', hours: 120 },
+    { value: '1w', label: '1W', hours: 168 },
+    { value: '4w', label: '4W', hours: 672 },
+    { value: '3mo', label: '3M', months: 3 },
+    { value: '6mo', label: '6M', months: 6 },
+    { value: '1y', label: '1Y', months: 12 },
+];
+/** Calendar subtraction clamps month-end and leap-day dates without rolling forward. */
+function monthsBefore(end, months) {
+    const start = new Date(end);
+    start.setUTCDate(1);
+    start.setUTCMonth(start.getUTCMonth() - months);
+    const lastDay = new Date(start);
+    lastDay.setUTCMonth(lastDay.getUTCMonth() + 1);
+    lastDay.setUTCDate(0);
+    start.setUTCDate(Math.min(end.getUTCDate(), lastDay.getUTCDate()));
+    return start;
+}
+/** Input values intentionally omit a zone; the UI explicitly labels them UTC. */
+export function presetRange(period, now = new Date()) {
+    const option = PERIODS.find((item) => item.value === period);
+    if (option === undefined)
+        throw new Error(`Unknown reporting period: ${period}`);
+    const end = new Date(Math.floor(now.getTime() / MINUTE_MS) * MINUTE_MS);
+    const start = 'hours' in option
+        ? new Date(end.getTime() - option.hours * 60 * MINUTE_MS)
+        : monthsBefore(end, option.months);
+    return { from: start.toISOString().slice(0, 16), to: end.toISOString().slice(0, 16) };
+}
+/** Preserve the initial thirty-day window while allowing minute precision. */
+export function defaultRange(now = new Date()) {
+    const end = new Date(Math.floor(now.getTime() / MINUTE_MS) * MINUTE_MS);
+    return {
+        from: new Date(end.getTime() - 30 * DAY_MS).toISOString().slice(0, 16),
+        to: end.toISOString().slice(0, 16),
+    };
+}
+export function rangeProblem(range) {
+    for (const value of [range.from, range.to]) {
+        const instant = Date.parse(`${value}:00Z`);
+        if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/.test(value) ||
+            !Number.isFinite(instant) ||
+            new Date(instant).toISOString().slice(0, 16) !== value) {
+            return 'Choose a valid start and end date and time (UTC).';
+        }
+    }
+    if (range.from >= range.to)
+        return 'The start must be before the end date and time.';
+    return undefined;
+}

package/dist/server.js

@@ -75,6 +75,7 @@
  * does not know is served as {@link DEFAULT_CONTENT_TYPE}, which a sniffing
  * browser is otherwise free to re-read as something it will execute.
  */
+import { parseViewGranularity, VIEW_GRANULARITIES } from './view-granularity.js';
 import { createServer } from 'node:http';
 import { join, sep } from 'node:path';
 import { FileNotFoundError } from 'blogwright-core';
@@ -121,7 +122,15 @@ const QUERY_ROUTE_PREFIX = '/api/queries/';
  * because its default is `config.analytics.bots`, applied inside the port -
  * this module must not restate it.
  */
-const QUERY_STRING_PARAMS = ['from', 'to', 'includeBots'];
+const QUERY_STRING_PARAMS = [
+    'from',
+    'to',
+    'includeBots',
+    'granularity',
+    'splitBots',
+    'path',
+    'country',
+];
 /** The two spellings the bot-inclusion flag takes, mapped to what it means. */
 const INCLUDE_BOTS_VALUES = { true: true, false: false };
 /**
@@ -291,15 +300,44 @@ function parseQueryParams(search) {
         }
     }
     const range = { from: requiredParam(search, 'from'), to: requiredParam(search, 'to') };
+    const interval = search.get('granularity');
+    let granularity;
+    if (interval !== null) {
+        if (search.getAll('granularity').length !== 1)
+            throw new RequestRejected(400, 'granularity must be provided once');
+        try {
+            granularity = parseViewGranularity(interval);
+        }
+        catch (err) {
+            throw new RequestRejected(400, describeError(err));
+        }
+    }
+    const country = search.get('country');
+    if (search.getAll('country').length > 1)
+        throw new RequestRejected(400, 'country must be provided once');
+    const path = search.get('path');
+    if (search.getAll('path').length > 1)
+        throw new RequestRejected(400, 'path must be provided once');
+    const split = search.get('splitBots');
+    if (split !== null &&
+        (search.getAll('splitBots').length !== 1 || !Object.hasOwn(INCLUDE_BOTS_VALUES, split))) {
+        throw new RequestRejected(400, 'splitBots must be provided once as true or false');
+    }
+    const extra = {
+        ...(path === null ? {} : { path }),
+        ...(country === null ? {} : { country }),
+        ...(granularity === undefined ? {} : { granularity }),
+        ...(split === null ? {} : { splitBots: INCLUDE_BOTS_VALUES[split] }),
+    };
     const flag = search.get('includeBots');
     if (flag === null) {
         // Absent on purpose: `config.analytics.bots` decides, inside the port.
-        return { range };
+        return { range, ...extra };
     }
     if (!Object.hasOwn(INCLUDE_BOTS_VALUES, flag)) {
         throw new RequestRejected(400, `query parameter "includeBots" must be ${Object.keys(INCLUDE_BOTS_VALUES).join(' or ')}, got "${flag}"`);
     }
-    return { range, includeBots: INCLUDE_BOTS_VALUES[flag] };
+    return { range, ...extra, includeBots: INCLUDE_BOTS_VALUES[flag] };
 }
 /**
  * Start the dashboard's HTTP listener on {@link LOOPBACK_ADDRESS}. Resolves
@@ -391,8 +429,12 @@ export async function createDashboardServer(opts) {
         const rows = await opts.query.run(resolved.name, params);
         return {
             name: resolved.name,
-            rowMeaning: definition.rowMeaning,
-            resultColumns: definition.resultColumns,
+            rowMeaning: resolved.name === 'views-over-time' &&
+                params.granularity !== undefined &&
+                params.granularity !== '24h'
+                ? `one UTC bucket of ${VIEW_GRANULARITIES[params.granularity].label}, labelled by its start, and the number of requests served in it`
+                : definition.rowMeaning,
+            resultColumns: resolved.resultColumns,
             rows,
         };
     }

package/dist/traffic-breakdown.d.ts

@@ -0,0 +1,2 @@
+/** Fixed SQL projections for disjoint bot/non-bot contributions to report totals. */
+export declare function withTrafficBreakdown(name: string, statement: string): string;

package/dist/traffic-breakdown.js

@@ -0,0 +1,15 @@
+/** Fixed SQL projections for disjoint bot/non-bot contributions to report totals. */
+export function withTrafficBreakdown(name, statement) {
+    if (name === 'unique-visitors') {
+        return statement
+            .replace('count(DISTINCT visitor_key) AS daily_unique_visitors', 'count(DISTINCT visitor_key) AS daily_unique_visitors, count(DISTINCT visitor_key) FILTER (WHERE NOT coalesce(is_bot, false)) AS non_bot')
+            .replace('SELECT day,\n       daily_unique_visitors,', 'SELECT day,\n       daily_unique_visitors, non_bot, daily_unique_visitors - non_bot AS bot,');
+    }
+    if (name === 'cache-hit-ratio') {
+        return statement
+            .replace('AS cache_hits\n', "AS cache_hits, count(*) FILTER (WHERE result_type IN ('Hit', 'RefreshHit') AND coalesce(is_bot, false)) AS bot_hits\n")
+            .replace('AS cache_hit_ratio\n', 'AS cache_hit_ratio, CAST(bot_hits AS DOUBLE) / requests AS bot, CAST(cache_hits - bot_hits AS DOUBLE) / requests AS non_bot\n');
+    }
+    const projection = name === 'row-count' ? 'count(*) AS row_count' : 'count(*) AS views';
+    return statement.replace(projection, `${projection}, count(*) FILTER (WHERE coalesce(is_bot, false)) AS bot, count(*) FILTER (WHERE NOT coalesce(is_bot, false)) AS non_bot`);
+}

package/dist/transform/diagnostics.d.ts

@@ -0,0 +1,17 @@
+/** Bounded transform events: fixed categories only, never input or error details. */
+export interface TransformBatchDiagnostic {
+    readonly event: 'transform_batch';
+    mapped: number;
+    processingFailed: number;
+    reasons: {
+        invalid_payload: number;
+        schema_rejected: number;
+    };
+}
+/** One event per completed batch and per uncached secret read, including retries. */
+export type TransformDiagnostic = TransformBatchDiagnostic | {
+    readonly event: 'salt_read';
+    readonly outcome: 'success' | 'failure';
+};
+/** Diagnostic sinks must return normally so observation cannot change delivery. */
+export type TransformDiagnostics = (event: TransformDiagnostic) => void;

package/dist/transform/diagnostics.js

@@ -0,0 +1 @@
+export {};