blogwright-analytics 0.3.3

package/dist/queries.js

@@ -0,0 +1,414 @@
+/**
+ * The fixed set of named, parameterised queries this package answers from -
+ * never SQL supplied by a client. Seven of them are the dashboard's panels;
+ * see [the change spec's §Analytics dashboard → Local
+ * server](../../../.specs/changes/merged/2026-07-26-analytics_plugin.md). The eighth,
+ * {@link ROW_COUNT_QUERY}, serves `analytics status`, and is here for the same
+ * reason the other seven are: a command reaches the table through the
+ * `AnalyticsQuery` port, and the port takes a name from this set, never a
+ * statement.
+ *
+ * **Parameterised is a shape here, not a convention.** A definition's SQL is
+ * built by the {@link sql} tag, whose only substitution slot accepts
+ * {@link SqlRelation} - a branded type whose single inhabitant is
+ * {@link PAGE_VIEWS}, declared in this module. Interpolating anything else is
+ * a compile error (`TS2345: Argument of type 'string' is not assignable to
+ * parameter of type 'SqlRelation'`), and a plain string cannot be assigned to
+ * {@link SqlText} either (`TS2322`), so a definition has nowhere to put a
+ * caller's value: caller values reach the statement only as `$name`
+ * placeholders, bound by {@link prepareQuery}. The tag is module-private, so
+ * no other module can mint SQL for this port at all.
+ *
+ * **The type-level block is the one holding the property; the runtime tests
+ * are a partial net under it, not a second copy of it.** `tsc` rejects *every*
+ * splice of a caller value that is not deliberately cast, and `pnpm typecheck`
+ * runs it in CI (`.github/workflows/ci.yml:22`). The tests in
+ * `queries.test.ts` catch only what a splice leaves visible in the finished
+ * string - a quoted literal the definition did not declare, or anything
+ * day-shaped. They do not catch the rest: splicing `'0 OR 1=1'` into
+ * `status-codes` as `` AND status >= ${'0 OR 1=1'} `` leaves the whole suite
+ * green while `tsc` reports `TS2345` (observed, 2026-08-30). What the net does
+ * still add is independence over the forms it does cover: vitest transpiles
+ * without typechecking, so `` AND day >= '${'2026-08-01' as SqlRelation}' ``
+ * passes `tsc` and reddens the parameterisation test anyway. Read the two as a
+ * check total up to a deliberate cast and a partial backstop under it, not as
+ * equals - weakening or dropping the branded types because "the tests cover
+ * it" would leave only the partial net.
+ *
+ * **Why the relation is a fixed name rather than the configured triple.** SQL
+ * binds *values*, not identifiers: a configured `<tableBucket>/<namespace>/
+ * <table>` spliced into the statement would be exactly the interpolation this
+ * module exists to make impossible. So every definition reads one relation,
+ * {@link PAGE_VIEWS_RELATION}, and binding that name to the configured triple
+ * is the adapter's job - it holds the plugin context, so it takes
+ * `resolveAnalyticsConfig(ctx)` and attaches or aliases accordingly. The
+ * configurability task 44 declares is therefore preserved, in the one place
+ * that has the environment to resolve it.
+ *
+ * Pure data and pure functions only: no `node:` builtin, no vendor SDK, no
+ * `fetch`. Nothing here runs a statement - that is `AnalyticsQuery`'s adapter.
+ */
+/**
+ * The relation every named query reads. Not "the configured table name" - the
+ * adapter binds this name to the configured `<namespace>.<table>` inside the
+ * attached catalog before it runs anything, and this module never sees the
+ * configuration. See the module doc comment for why an identifier cannot be a
+ * bind parameter.
+ */
+export const PAGE_VIEWS_RELATION = 'page_views';
+/** {@link PAGE_VIEWS_RELATION} as the one value the {@link sql} tag will splice. */
+const PAGE_VIEWS = PAGE_VIEWS_RELATION;
+/**
+ * Build a definition's statement. The rest parameter is typed
+ * {@link SqlRelation}, so `` sql`... WHERE day > ${params.range.from}` `` does
+ * not compile; a caller's value has to go through a `$name` placeholder.
+ */
+function sql(fragments, ...relations) {
+    return fragments
+        .reduce((text, fragment, index) => text + (relations[index - 1] ?? '') + fragment)
+        .trim();
+}
+/**
+ * The parameters a definition binds, as `$name` placeholders in its SQL. Every
+ * query takes the date range and the bot-inclusion flag the spec requires of
+ * 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'];
+/**
+ * The `x-edge-result-type` values CloudFront reports for a cache hit. AWS
+ * documents that field's values as `Hit`, `RefreshHit`, `Miss`,
+ * `LimitExceeded`, `CapacityExceeded`, `Error` and `Redirect`; the first two
+ * are the hits. `OriginShieldHit` is deliberately absent - it is an
+ * `x-edge-detailed-result-type` value, and `schema.ts` selects
+ * `x-edge-result-type` rather than the detailed field, so it can never appear
+ * in `result_type`.
+ */
+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
+ * because the command may not write SQL: every statement this package runs is
+ * one of these definitions, reached through the `AnalyticsQuery` port.
+ */
+export const ROW_COUNT_QUERY = 'row-count';
+/** The one column {@link ROW_COUNT_QUERY} selects. Named so no caller spells it twice. */
+export const ROW_COUNT_COLUMN = 'row_count';
+/**
+ * The range {@link ROW_COUNT_QUERY} is asked over when the caller wants the
+ * whole table, as `analytics status` does.
+ *
+ * Every definition in this set is bounded on the `day` partition - the spec
+ * requires the range and the bot flag of all of them - so "the whole table" is
+ * expressed as the widest range the column can hold rather than as an
+ * unbounded statement. Both ends are calendar days {@link isCalendarDay}
+ * accepts, so this constant goes through exactly the validation a caller's
+ * range does. `from` is the Unix epoch, which no `day` can precede: the column
+ * is derived from the request's own timestamp. `to` is the last day of the
+ * four-digit years, which is the largest day this module's `YYYY-MM-DD` shape
+ * can express at all.
+ */
+export const WHOLE_TABLE_RANGE = { from: '1970-01-01', to: '9999-12-31' };
+/**
+ * Every named query, keyed by the name a caller asks for: the seven the spec's
+ * §Local server lists, in its order, and then {@link ROW_COUNT_QUERY}, which
+ * no panel draws and `analytics status` reports.
+ *
+ * Every statement reads {@link PAGE_VIEWS}, bounds itself on the `day`
+ * partition with `$from`/`$to`, and honours `$include_bots` - a row whose
+ * `is_bot` is null counts as not-a-bot, since the transform leaves the column
+ * absent when it has nothing to say.
+ *
+ * **`unique-visitors` is the one whose semantic cannot be read off its name.**
+ * `visitor_key` is a daily-salted digest and the salt turns over at every UTC
+ * day boundary (the spec's Decision *Daily salt rotation stands*, settled
+ * 2026-07-27), so the same person is a different `visitor_key` tomorrow.
+ * A `count(DISTINCT visitor_key)` spanning a range therefore does not error -
+ * it returns a plausible number that means nothing. The definition counts
+ * distinct keys *within* a day and reports the range total as the sum of those
+ * daily counts, and says so in its column names (`daily_unique_visitors`,
+ * `summed_daily_unique_visitors`) and its `rowMeaning`, so a dashboard cannot
+ * relabel the total "unique visitors" without deleting the words that say
+ * otherwise. The sum over-counts a visitor who returns on another day; that is
+ * the accepted cost of bounding what one day of brute-forced salt could ever
+ * correlate.
+ */
+export const ANALYTICS_QUERIES = {
+    'views-over-time': {
+        rowMeaning: 'one UTC day and the number of requests served that day',
+        columns: ['day', 'is_bot'],
+        binds: ['from', 'to', 'include_bots'],
+        resultColumns: ['day', 'views'],
+        literals: [],
+        sql: sql `
+SELECT 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 day
+ORDER BY day
+`,
+    },
+    'top-paths': {
+        rowMeaning: 'one request path and the number of requests for it over the range',
+        columns: ['day', 'uri', 'is_bot'],
+        binds: ['from', 'to', 'include_bots'],
+        resultColumns: ['uri', 'views'],
+        literals: [],
+        sql: sql `
+SELECT uri, 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 uri
+ORDER BY views DESC, uri
+`,
+    },
+    referrers: {
+        rowMeaning: 'one referring URL and the number of requests it sent over the range',
+        columns: ['day', 'referrer', 'is_bot'],
+        binds: ['from', 'to', 'include_bots'],
+        resultColumns: ['referrer', 'views'],
+        literals: [],
+        sql: sql `
+SELECT referrer, 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))
+  AND referrer IS NOT NULL
+GROUP BY referrer
+ORDER BY views DESC, referrer
+`,
+    },
+    countries: {
+        rowMeaning: 'one viewer country and the number of requests from it over the range',
+        columns: ['day', 'country', 'is_bot'],
+        binds: ['from', 'to', 'include_bots'],
+        resultColumns: ['country', 'views'],
+        literals: [],
+        sql: sql `
+SELECT country, 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))
+  AND country IS NOT NULL
+GROUP BY country
+ORDER BY views DESC, country
+`,
+    },
+    'status-codes': {
+        rowMeaning: 'one HTTP status code and the number of responses carrying it over the range',
+        columns: ['day', 'status', 'is_bot'],
+        binds: ['from', 'to', 'include_bots'],
+        resultColumns: ['status', 'views'],
+        literals: [],
+        sql: sql `
+SELECT status, 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 status
+ORDER BY status
+`,
+    },
+    'cache-hit-ratio': {
+        rowMeaning: 'one UTC day, its requests, the edge cache hits among them, and hits divided by requests',
+        columns: ['day', 'result_type', 'is_bot'],
+        binds: ['from', 'to', 'include_bots'],
+        resultColumns: ['day', 'requests', 'cache_hits', 'cache_hit_ratio'],
+        literals: CACHE_HIT_RESULT_TYPES,
+        sql: sql `
+WITH daily AS (
+  SELECT day,
+         count(*) AS requests,
+         count(*) FILTER (WHERE result_type IN ('Hit', 'RefreshHit')) AS cache_hits
+  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 day
+)
+SELECT day, requests, cache_hits, CAST(cache_hits AS DOUBLE) / requests AS cache_hit_ratio
+FROM daily
+ORDER BY day
+`,
+    },
+    'unique-visitors': {
+        rowMeaning: 'one UTC day and its distinct visitor_key count, beside the range total - the sum of those daily counts, not a distinct count across days, because the salt rotates daily',
+        columns: ['day', 'visitor_key', 'is_bot'],
+        binds: ['from', 'to', 'include_bots'],
+        resultColumns: ['day', 'daily_unique_visitors', 'summed_daily_unique_visitors'],
+        literals: [],
+        sql: sql `
+WITH daily AS (
+  SELECT day, count(DISTINCT visitor_key) AS daily_unique_visitors
+  FROM ${PAGE_VIEWS}
+  WHERE day BETWEEN CAST($from AS DATE) AND CAST($to AS DATE)
+    AND ($include_bots OR NOT coalesce(is_bot, false))
+    AND visitor_key IS NOT NULL
+  GROUP BY day
+)
+SELECT day,
+       daily_unique_visitors,
+       sum(daily_unique_visitors) OVER () AS summed_daily_unique_visitors
+FROM daily
+ORDER BY day
+`,
+    },
+    /**
+     * Not a dashboard panel: the figure `analytics status` reports beside the
+     * node listing, so an operator can tell "the pipeline is provisioned" from
+     * "the pipeline has delivered something". Bots are counted when the caller
+     * asks for them - a row is a row - which is why the status command binds
+     * `include_bots` explicitly rather than leaving it to `config.analytics.bots`.
+     */
+    [ROW_COUNT_QUERY]: {
+        rowMeaning: 'the number of rows the table holds over the range, one row carrying the count',
+        columns: ['day', 'is_bot'],
+        binds: ['from', 'to', 'include_bots'],
+        resultColumns: [ROW_COUNT_COLUMN],
+        literals: [],
+        sql: sql `
+SELECT count(*) AS row_count
+FROM ${PAGE_VIEWS}
+WHERE day BETWEEN CAST($from AS DATE) AND CAST($to AS DATE)
+  AND ($include_bots OR NOT coalesce(is_bot, false))
+`,
+    },
+};
+/**
+ * Every query name, in declaration order - what the unknown-name error lists
+ * and what the test suite iterates. Derived from the table rather than
+ * restated beside it, so the two cannot drift; the cast is `Object.keys`'
+ * `string[]` narrowed back to the keys it just enumerated.
+ */
+export const ANALYTICS_QUERY_NAMES = Object.keys(ANALYTICS_QUERIES);
+/**
+ * Whether bot-flagged rows are counted when a caller states no preference, per
+ * `bots` mode. Exhaustive over the union rather than a comparison against one
+ * spelling, so adding a third mode to task 44's config is a compile error here
+ * instead of a silent `false`. The *default value* is not restated: it is
+ * whatever `validateAnalyticsConfig` put on `config.bots`.
+ */
+const BOTS_INCLUDED_BY_DEFAULT = {
+    flag: true,
+    filter: false,
+};
+/**
+ * A `YYYY-MM-DD` day, the form the `day` partition column takes. Four digits,
+ * so the extended-year forms `Date` also understands are not days here - see
+ * {@link isCalendarDay} for which of the two checks catches what.
+ */
+const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+/** Characters in a `YYYY-MM-DD` day - how much of an ISO timestamp is the day. */
+const DAY_LENGTH = 10;
+/** Render a rejected value for a message: strings quoted, as core's config messages quote them. */
+function describeValue(value) {
+    return typeof value === 'string' ? `"${value}"` : String(value);
+}
+/**
+ * Whether `day` names a day that exists. Neither half is redundant, and they
+ * catch different things:
+ *
+ * - The round-trip is what rejects a *malformed or impossible* day, and it
+ *   does most of the work. `Date.parse('2026-02-30T00:00:00Z')` does not fail,
+ *   it rolls over to 2 March, so a mistyped range end would silently report a
+ *   different month; comparing the parsed date's own ISO form back against the
+ *   input catches that, and also catches `2026-8-1`, `20260801` and a day with
+ *   a time already on it, which all parse to `NaN` here.
+ * - {@link DAY_PATTERN} is what rejects the *extended-year* forms `Date` also
+ *   accepts. `'+271821-04'` is ten characters long and round-trips exactly -
+ *   `new Date(Date.parse('+271821-04T00:00:00Z')).toISOString().slice(0, 10)`
+ *   is `'+271821-04'` - so without the pattern it would be bound as a day and
+ *   reach `CAST($from AS DATE)`. `'-000001-01'` likewise.
+ *
+ * `queries.test.ts` pins both: drop either line and a different test reddens.
+ */
+function isCalendarDay(day) {
+    if (!DAY_PATTERN.test(day))
+        return false;
+    const time = Date.parse(`${day}T00:00:00Z`);
+    if (Number.isNaN(time))
+        return false;
+    return new Date(time).toISOString().slice(0, DAY_LENGTH) === day;
+}
+/**
+ * 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
+ * this is the boundary the local server's HTTP path arrives at, where the
+ * compiler's guarantee has already been erased.
+ *
+ * The lookup is guarded by `Object.hasOwn` and not by a test for `undefined`,
+ * for the reason `build.ts`'s `contentType` is: an unguarded index answers
+ * every `Object.prototype` key with an inherited function, so
+ * `GET /api/queries/constructor` would resolve to a truthy "definition" and
+ * fail later as `definition.binds is not iterable` instead of the rejection
+ * below. The names in the message are the only ones that resolve.
+ */
+export function queryDefinition(name) {
+    const definition = Object.hasOwn(ANALYTICS_QUERIES, name)
+        ? ANALYTICS_QUERIES[name]
+        : undefined;
+    if (definition === undefined) {
+        throw new Error(`unknown analytics query ${describeValue(name)} - available queries are ${ANALYTICS_QUERY_NAMES.join(', ')}`);
+    }
+    return definition;
+}
+/**
+ * Check the range at the same boundary the name is checked at, naming the
+ * offending value. The declared type says `from` and `to` are present strings,
+ * and the runtime says otherwise for the same reason `config.ts`'s
+ * `unsealEnvDerivedOverrides` does: the one seam that fills these is the
+ * dashboard's query string, where every value arrives as `string | undefined`
+ * and a narrowing can be forgotten. Defaulting an absent range would be worse
+ * than raising - a chart over "some window the server picked" is indexed by
+ * nothing the reader chose.
+ */
+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 to !== 'string' || !isCalendarDay(to)) {
+        throw new Error(`analytics query ${describeValue(name)}: range.to must be a YYYY-MM-DD calendar day, got ${describeValue(to)}`);
+    }
+    // Both are `YYYY-MM-DD`, so lexical order is chronological order.
+    if (from > to) {
+        throw new Error(`analytics query ${describeValue(name)}: range is inverted - from ${describeValue(from)} is after to ${describeValue(to)}`);
+    }
+    return { from, to };
+}
+/**
+ * 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
+ * both rejected, so every implementation of `AnalyticsQuery` (the DuckDB
+ * adapter and the fixture-backed fake alike) refuses the same inputs with the
+ * same messages.
+ *
+ * `config` is the validated `analytics` block off `ctx.pluginConfig`, taken for
+ * its `bots` mode alone: a resolved config satisfies it too, so a caller passes
+ * whichever it is holding.
+ */
+export function prepareQuery(name, params, config) {
+    const definition = queryDefinition(name);
+    const range = validateRange(name, params.range);
+    const includeBots = params.includeBots ?? BOTS_INCLUDED_BY_DEFAULT[config.bots];
+    const available = {
+        from: range.from,
+        to: range.to,
+        include_bots: includeBots,
+    };
+    const bindings = {};
+    for (const bind of definition.binds)
+        bindings[bind] = available[bind];
+    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,
+        bindings,
+    };
+}

package/dist/schema.d.ts

@@ -0,0 +1,240 @@
+/**
+ * The single home for the `page_views` Iceberg table: its column set, its
+ * `day` partition, the CloudFront standard-logging (v2) fields the delivery
+ * selects, and the mapping between the two. The transform Lambda, the table
+ * node and the delivery node all read these constants instead of restating
+ * them - see [§Table schema](../../../.specs/changes/merged/2026-07-26-analytics_plugin.md).
+ *
+ * Why this file is worth being careful with: Firehose matches incoming JSON
+ * keys to Iceberg column names **exactly** and silently discards any field
+ * that does not match a column - no error, no dead-letter record, nothing
+ * that shows up in a log. A typo here does not fail loudly; it fills a
+ * column with nulls forever, and nothing points back at this file as the
+ * cause. Column names are lowercase throughout - an S3 Tables catalog
+ * requirement, not a style choice.
+ *
+ * `cs(Cookie)` and `x-forwarded-for` carry personal data and have no
+ * analytic use, so they are never selected: they never reach Firehose, the
+ * transform, or the table. This governs the analytics delivery only. The
+ * site's existing CloudWatch delivery (`packages/cli/src/nodes.ts`'s
+ * `logDeliveryNode`, wired through `packages/core/src/aws/logs.ts`'s
+ * `createDelivery`) is created with no `recordFields`, so AWS's default
+ * field list - which includes both excluded fields - still applies to that
+ * copy. Narrowing that is a separate change to the site's node, not this
+ * one; do not "fix" that inconsistency here.
+ *
+ * Field names are verified against AWS's CloudFront standard-logging (v2)
+ * documentation (docs.aws.amazon.com/AmazonCloudFront, "Configure standard
+ * logging (v2)" and "Standard logging reference", current as of 2026-08-30):
+ * the `recordFields` the CreateDelivery API accepts, and the field
+ * descriptions in the log-file-field reference.
+ *
+ * Pure data and pure functions only: no `node:` builtin, no vendor SDK, no
+ * `fetch`.
+ */
+/**
+ * Iceberg primitive types used by the `page_views` table. Not exported: no
+ * consumer needs the bare union today - a future one can reach the same
+ * type as `PageViewsColumn['icebergType']`. Export it once a real consumer
+ * needs the union by name.
+ */
+type IcebergType = 'string' | 'timestamp' | 'date' | 'int' | 'long' | 'double' | 'boolean';
+/** One `page_views` column: its Iceberg type and whether Firehose may write a null. */
+export interface PageViewsColumn {
+    readonly name: string;
+    readonly icebergType: IcebergType;
+    readonly required: boolean;
+}
+/**
+ * The `page_views` table, in the order the spec's `PageView` `$defs` block
+ * lists it. `required` is `true` exactly for the spec's `PageView.required`
+ * set (`event_time`, `day`, `host`, `uri`, `status`); every other column may
+ * be null - CloudFront itself writes `-` for several of these when a request
+ * has nothing to say (no referrer, no query string, and so on).
+ */
+export declare const PAGE_VIEWS_COLUMNS: readonly [{
+    readonly name: "event_time";
+    readonly icebergType: "timestamp";
+    readonly required: true;
+}, {
+    readonly name: "day";
+    readonly icebergType: "date";
+    readonly required: true;
+}, {
+    readonly name: "host";
+    readonly icebergType: "string";
+    readonly required: true;
+}, {
+    readonly name: "uri";
+    readonly icebergType: "string";
+    readonly required: true;
+}, {
+    readonly name: "query";
+    readonly icebergType: "string";
+    readonly required: false;
+}, {
+    readonly name: "method";
+    readonly icebergType: "string";
+    readonly required: false;
+}, {
+    readonly name: "status";
+    readonly icebergType: "int";
+    readonly required: true;
+}, {
+    readonly name: "referrer";
+    readonly icebergType: "string";
+    readonly required: false;
+}, {
+    readonly name: "user_agent";
+    readonly icebergType: "string";
+    readonly required: false;
+}, {
+    readonly name: "country";
+    readonly icebergType: "string";
+    readonly required: false;
+}, {
+    readonly name: "asn";
+    readonly icebergType: "string";
+    readonly required: false;
+}, {
+    readonly name: "edge_location";
+    readonly icebergType: "string";
+    readonly required: false;
+}, {
+    readonly name: "result_type";
+    readonly icebergType: "string";
+    readonly required: false;
+}, {
+    readonly name: "bytes_sent";
+    readonly icebergType: "long";
+    readonly required: false;
+}, {
+    readonly name: "time_taken";
+    readonly icebergType: "double";
+    readonly required: false;
+}, {
+    readonly name: "content_type";
+    readonly icebergType: "string";
+    readonly required: false;
+}, {
+    readonly name: "protocol";
+    readonly icebergType: "string";
+    readonly required: false;
+}, {
+    readonly name: "request_id";
+    readonly icebergType: "string";
+    readonly required: false;
+}, {
+    readonly name: "visitor_key";
+    readonly icebergType: "string";
+    readonly required: false;
+}, {
+    readonly name: "is_bot";
+    readonly icebergType: "boolean";
+    readonly required: false;
+}];
+/** Every valid `page_views` column name, derived from the table above. */
+export type PageViewColumnName = (typeof PAGE_VIEWS_COLUMNS)[number]['name'];
+/** `page_views` is partitioned by this column. */
+export declare const PAGE_VIEWS_PARTITION_COLUMN: PageViewColumnName;
+/** Maps an `IcebergType` to the TypeScript type `PageView` stores it as. */
+type TsTypeOf<T extends IcebergType> = T extends 'string' | 'timestamp' | 'date' ? string : T extends 'int' | 'long' | 'double' ? number : T extends 'boolean' ? boolean : never;
+type RequiredColumn = Extract<(typeof PAGE_VIEWS_COLUMNS)[number], {
+    required: true;
+}>;
+type OptionalColumn = Extract<(typeof PAGE_VIEWS_COLUMNS)[number], {
+    required: false;
+}>;
+/**
+ * One `page_views` row, derived from `PAGE_VIEWS_COLUMNS` rather than
+ * hand-typed, so the transform (which builds these) cannot invent a column
+ * name the table does not carry - a typo in a property name here is a
+ * compile error, not a silently-dropped Firehose field.
+ */
+export type PageView = {
+    [C in RequiredColumn as C['name']]: TsTypeOf<C['icebergType']>;
+} & {
+    [C in OptionalColumn as C['name']]?: TsTypeOf<C['icebergType']>;
+};
+/**
+ * The CloudFront viewer-IP field. Selected so the transform can derive
+ * `visitor_key` from it (IP + user agent + a secret daily salt); the raw
+ * value is discarded by the transform and never written to any column, so
+ * it has no entry in `FIELD_TO_COLUMN`.
+ */
+export declare const VIEWER_IP_FIELD = "c-ip";
+/**
+ * The CloudFront millisecond-epoch timestamp field. Selected so the
+ * transform can derive both `event_time` and the `day` partition from it;
+ * because it feeds two columns rather than renaming into one, it has no
+ * entry in `FIELD_TO_COLUMN` either. Exported for its one consumer,
+ * `transform/map-record.ts`, which reads the field off the record and must
+ * not spell its name a second time - the field name is not a valid column
+ * name, so a divergence between the two spellings would silently stop
+ * filling `event_time` and `day`.
+ */
+export declare const TIMESTAMP_MS_FIELD = "timestamp(ms)";
+/**
+ * Selected CloudFront fields that feed a `DERIVED_COLUMNS` entry instead of
+ * being renamed 1:1 into a column of their own.
+ */
+export declare const DERIVATION_ONLY_FIELDS: readonly ["c-ip", "timestamp(ms)"];
+/**
+ * The CloudFront standard-logging (v2) field name each `page_views` column
+ * is filled from, a straight rename with no other transformation. Field
+ * names and meanings are as AWS documents them under "Standard logging
+ * reference":
+ *
+ * - `x-host-header` (not `cs(Host)`) is the Host header the viewer actually
+ *   sent - the alternate domain name (CNAME) when the site has one, and the
+ *   distribution's own domain otherwise. `cs(Host)` always reports the raw
+ *   CloudFront distribution domain regardless of what the viewer requested,
+ *   which would make `host` a constant for every custom-domain site.
+ * - `x-edge-result-type` (not `x-edge-response-result-type` or
+ *   `x-edge-detailed-result-type`) is the standard hit/miss/error
+ *   classification after the response finished sending - the field AWS's own
+ *   sample cache-hit-ratio queries group by. The other two exist for
+ *   diagnosing mid-response client disconnects and origin-error detail,
+ *   which this table does not carry a column for.
+ * - `sc-bytes` (not `cs-bytes` or `sc-content-len`) is the total bytes
+ *   CloudFront sent to the viewer, matching `bytes_sent`; `cs-bytes` is the
+ *   viewer's request size and `sc-content-len` is only the `Content-Length`
+ *   header value.
+ */
+export declare const FIELD_TO_COLUMN: {
+    readonly 'x-host-header': "host";
+    readonly 'cs-uri-stem': "uri";
+    readonly 'cs-uri-query': "query";
+    readonly 'cs-method': "method";
+    readonly 'sc-status': "status";
+    readonly 'cs(Referer)': "referrer";
+    readonly 'cs(User-Agent)': "user_agent";
+    readonly 'c-country': "country";
+    readonly asn: "asn";
+    readonly 'x-edge-location': "edge_location";
+    readonly 'x-edge-result-type': "result_type";
+    readonly 'sc-bytes': "bytes_sent";
+    readonly 'time-taken': "time_taken";
+    readonly 'sc-content-type': "content_type";
+    readonly 'cs-protocol': "protocol";
+    readonly 'x-edge-request-id': "request_id";
+};
+/**
+ * The CloudFront fields the analytics delivery selects: every
+ * `FIELD_TO_COLUMN` key plus the two derivation-only inputs. `cs(Cookie)`
+ * and `x-forwarded-for` are deliberately absent - see the module doc comment.
+ */
+export declare const CLOUDFRONT_RECORD_FIELDS: readonly [...string[], "c-ip", "timestamp(ms)"];
+/**
+ * The four `page_views` columns no CloudFront field maps to 1:1 - each is
+ * computed by the transform from one or more selected fields rather than
+ * renamed from a single one:
+ *
+ * - `event_time` and `day` are both derived from `timestamp(ms)`.
+ * - `visitor_key` is a salted hash of `c-ip`, `cs(User-Agent)` and a secret
+ *   daily salt - no single field determines it.
+ * - `is_bot` is a user-agent match against `cs(User-Agent)`, which already
+ *   has its own entry in `FIELD_TO_COLUMN` (-> `user_agent`).
+ */
+export declare const DERIVED_COLUMNS: readonly ["event_time", "day", "visitor_key", "is_bot"];
+export {};