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

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/plugin.d.ts

@@ -51,11 +51,11 @@
  * They are both now, and `analytics status` still runs the declared command
  * above rather than the generic verb, because a declared action wins.
  *
- * The property `nodes` carries is not just "twelve nodes": it is that the
+ * The property `nodes` carries is not just "fourteen nodes": it is that the
  * CLI's engine reconciles them against the store `toPluginContext` scoped to
  * this plugin's name, `state/<env>.analytics.json` - never the site's
  * `state/<env>.json`. `blogwright bootstrap` therefore provisions none of
- * these twelve (the site's `buildNodes` does not consult discovery), and
+ * these fourteen (the site's `buildNodes` does not consult discovery), and
  * `blogwright destroy --yes` removes none of them, because
  * `assertNoScopedState` (`packages/cli/src/commands.ts`) refuses the site
  * teardown for as long as that scoped object exists and names

package/dist/plugin.js

@@ -51,11 +51,11 @@
  * They are both now, and `analytics status` still runs the declared command
  * above rather than the generic verb, because a declared action wins.
  *
- * The property `nodes` carries is not just "twelve nodes": it is that the
+ * The property `nodes` carries is not just "fourteen nodes": it is that the
  * CLI's engine reconciles them against the store `toPluginContext` scoped to
  * this plugin's name, `state/<env>.analytics.json` - never the site's
  * `state/<env>.json`. `blogwright bootstrap` therefore provisions none of
- * these twelve (the site's `buildNodes` does not consult discovery), and
+ * these fourteen (the site's `buildNodes` does not consult discovery), and
  * `blogwright destroy --yes` removes none of them, because
  * `assertNoScopedState` (`packages/cli/src/commands.ts`) refuses the site
  * teardown for as long as that scoped object exists and names

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 {
@@ -130,7 +139,7 @@ interface QueryDefinition {
  * The name of the row-count query. Not one of the seven the spec's §Local
  * server lists - those answer the dashboard's panels; this one answers
  * `analytics status`, which reports the table's current row count beside the
- * plugin's twelve nodes. It lives in this set rather than in the command
+ * plugin's fourteen nodes. It lives in this set rather than in the command
  * because the command may not write SQL: every statement this package runs is
  * one of these definitions, reached through the `AnalyticsQuery` port.
  */
@@ -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`,
@@ -89,7 +99,7 @@ const CACHE_HIT_RESULT_TYPES = ['Hit', 'RefreshHit'];
  * The name of the row-count query. Not one of the seven the spec's §Local
  * server lists - those answer the dashboard's panels; this one answers
  * `analytics status`, which reports the table's current row count beside the
- * plugin's twelve nodes. It lives in this set rather than in the command
+ * plugin's fourteen nodes. It lives in this set rather than in the command
  * because the command may not write SQL: every statement this package runs is
  * one of these definitions, reached through the `AnalyticsQuery` port.
  */
@@ -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 {};

package/dist/transform/handler.d.ts

@@ -6,9 +6,10 @@
  * prefix rather than failing the batch" - plus the cold-start secret read step
  * 3 calls for.
  *
- * It owns four things and nothing else: the envelope types, the base64 and
+ * It owns the envelope types, the base64 and
  * JSON boundary, the cold-start read of the long-lived salt secret, and the
- * translation of one `MapRecordResult` into one Firehose response entry. Every
+ * translation of one `MapRecordResult` into one Firehose response entry, plus
+ * bounded diagnostics through an injected port. Every
  * decision about *what a row is* - which field fills which column, which
  * values are unusable, how `visitor_key` is derived and under which day's salt
  * - belongs to `map-record.ts` and is forwarded here, never re-decided.
@@ -42,8 +43,7 @@
  * over a 2^32 space. A blanket catch around `mapRecord` would convert those
  * throws into `ProcessingFailed` for every record - the whole batch to the
  * error prefix, no error anywhere, an empty dashboard, and nothing to say why.
- * So the only `try` in this module is the one around `JSON.parse`, which is
- * this module's own boundary. A throw from the mapping propagates, the
+ * The mapping remains outside the JSON boundary catch. A throw from the mapping propagates, the
  * invocation fails, and Firehose retries the batch and raises its own error
  * metric. Loudly is the point.
  *
@@ -69,6 +69,7 @@
  * caller that hands the constructed handler to Lambda.
  */
 import type { SecretsManagerClient } from 'blogwright-core';
+import type { TransformDiagnostics } from './diagnostics.js';
 /**
  * One record as Firehose sends it. The event carries more - `invocationId`,
  * `deliveryStreamArn`, `region`, and per-record source metadata - and this
@@ -131,5 +132,5 @@ type Environment = Readonly<Record<string, string | undefined>>;
  * call disable an execution environment for its whole life, failing every
  * batch it ever sees; leaving it uncached means the next invocation retries.
  */
-export declare function createTransformHandler(secrets: SaltSecretStore, env?: Environment): (request: FirehoseTransformRequest) => Promise<FirehoseTransformResponse>;
+export declare function createTransformHandler(secrets: SaltSecretStore, env: Environment, diagnostics?: TransformDiagnostics): (request: FirehoseTransformRequest) => Promise<FirehoseTransformResponse>;
 export {};

package/dist/transform/handler.js

@@ -6,9 +6,10 @@
  * prefix rather than failing the batch" - plus the cold-start secret read step
  * 3 calls for.
  *
- * It owns four things and nothing else: the envelope types, the base64 and
+ * It owns the envelope types, the base64 and
  * JSON boundary, the cold-start read of the long-lived salt secret, and the
- * translation of one `MapRecordResult` into one Firehose response entry. Every
+ * translation of one `MapRecordResult` into one Firehose response entry, plus
+ * bounded diagnostics through an injected port. Every
  * decision about *what a row is* - which field fills which column, which
  * values are unusable, how `visitor_key` is derived and under which day's salt
  * - belongs to `map-record.ts` and is forwarded here, never re-decided.
@@ -42,8 +43,7 @@
  * over a 2^32 space. A blanket catch around `mapRecord` would convert those
  * throws into `ProcessingFailed` for every record - the whole batch to the
  * error prefix, no error anywhere, an empty dashboard, and nothing to say why.
- * So the only `try` in this module is the one around `JSON.parse`, which is
- * this module's own boundary. A throw from the mapping propagates, the
+ * The mapping remains outside the JSON boundary catch. A throw from the mapping propagates, the
  * invocation fails, and Firehose retries the batch and raises its own error
  * metric. Loudly is the point.
  *
@@ -135,13 +135,20 @@ function decodePayload(data) {
  * carries records of two days, and one salt chosen per invocation would be the
  * wrong day's for every record on the far side of it.
  */
-function transformRecord(record, saltSecret) {
+function transformRecord(record, saltSecret, counts) {
     const payload = decodePayload(record.data);
-    if (payload === undefined)
+    if (payload === undefined) {
+        counts.processingFailed += 1;
+        counts.reasons.invalid_payload += 1;
         return { recordId: record.recordId, result: PROCESSING_FAILED };
+    }
     const mapped = mapRecord(payload, saltSecret);
-    if (!mapped.mapped)
+    if (!mapped.mapped) {
+        counts.processingFailed += 1;
+        counts.reasons.schema_rejected += 1;
         return { recordId: record.recordId, result: PROCESSING_FAILED };
+    }
+    counts.mapped += 1;
     return {
         recordId: record.recordId,
         result: OK,
@@ -162,16 +169,32 @@ function transformRecord(record, saltSecret) {
  * call disable an execution environment for its whole life, failing every
  * batch it ever sees; leaving it uncached means the next invocation retries.
  */
-export function createTransformHandler(secrets, env = process.env) {
+export function createTransformHandler(secrets, env, diagnostics = () => { }) {
     const secretName = requireSaltSecretName(env);
     let cached;
     async function readSaltSecret() {
-        if (cached === undefined)
-            cached = await loadSaltSecret(secrets, secretName);
+        if (cached === undefined) {
+            try {
+                cached = await loadSaltSecret(secrets, secretName);
+            }
+            catch (error) {
+                diagnostics({ event: 'salt_read', outcome: 'failure' });
+                throw error;
+            }
+            diagnostics({ event: 'salt_read', outcome: 'success' });
+        }
         return cached;
     }
     return async function transformFirehoseRecords(request) {
         const saltSecret = await readSaltSecret();
-        return { records: request.records.map((record) => transformRecord(record, saltSecret)) };
+        const counts = {
+            event: 'transform_batch',
+            mapped: 0,
+            processingFailed: 0,
+            reasons: { invalid_payload: 0, schema_rejected: 0 },
+        };
+        const records = request.records.map((record) => transformRecord(record, saltSecret, counts));
+        diagnostics(counts);
+        return { records };
     };
 }