blogwright-analytics 0.3.3

package/dist/queries.d.ts

@@ -0,0 +1,301 @@
+/**
+ * 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.
+ */
+import type { AnalyticsConfig } from './config.js';
+import type { PageViewColumnName } from './schema.js';
+/**
+ * A statement one of the named definitions carries. Branded, and the brand's
+ * symbol is not exported, so the only way to a value of this type is the
+ * {@link sql} tag below - and the tag is module-private too. A `string` is not
+ * assignable to it.
+ */
+declare const SQL_TEXT: unique symbol;
+type SqlText = string & {
+    readonly [SQL_TEXT]: true;
+};
+/**
+ * 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 declare const PAGE_VIEWS_RELATION = "page_views";
+/**
+ * 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.
+ */
+declare const QUERY_PARAM_NAMES: readonly ["from", "to", "include_bots"];
+/** 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. */
+interface DateRange {
+    /** First day of the range, inclusive. */
+    readonly from: string;
+    /** Last day of the range, inclusive. */
+    readonly to: string;
+}
+/**
+ * What a caller hands {@link AnalyticsQuery.run}. `includeBots` is optional
+ * because its default is not this module's to state: it comes from
+ * `config.analytics.bots` (task 44) through {@link BOTS_INCLUDED_BY_DEFAULT}.
+ */
+export interface QueryParams {
+    /** The days to report over. */
+    readonly range: DateRange;
+    /**
+     * Whether bot-flagged rows are counted. Absent means "whatever
+     * `config.analytics.bots` says": `flag` keeps them, `filter` excludes them.
+     * Records are stored either way - filtering is a query concern, per the
+     * spec's Decision *Flag bots, do not drop them*.
+     */
+    readonly includeBots?: boolean | undefined;
+}
+/** One named query: its statement, what it reads, what it binds, what it returns. */
+interface QueryDefinition {
+    /**
+     * What one result row means, in one line. The dashboard renders it beside
+     * the chart, which is why `unique-visitors` says "summed daily uniques"
+     * here as well as in its column names - see {@link ANALYTICS_QUERIES}.
+     */
+    readonly rowMeaning: string;
+    /** The `page_views` columns the statement reads, typed against `schema.ts`. */
+    readonly columns: readonly PageViewColumnName[];
+    /** The placeholders the statement carries, one bound value each. */
+    readonly binds: readonly QueryParamName[];
+    /** The columns a result row carries, in the order the statement selects them. */
+    readonly resultColumns: readonly string[];
+    /**
+     * Constants the statement spells for itself, quoted inside the SQL. Declared
+     * so the parameterisation test can tell a domain constant from an
+     * interpolated caller value: any literal in the SQL that is not on this list
+     * fails, naming the query.
+     */
+    readonly literals: readonly string[];
+    /** The statement. Only {@link sql} can produce one. */
+    readonly sql: SqlText;
+}
+/**
+ * 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 declare const ROW_COUNT_QUERY = "row-count";
+/** The one column {@link ROW_COUNT_QUERY} selects. Named so no caller spells it twice. */
+export declare 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 declare const WHOLE_TABLE_RANGE: {
+    readonly from: "1970-01-01";
+    readonly 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 declare const ANALYTICS_QUERIES: {
+    readonly 'views-over-time': {
+        readonly rowMeaning: "one UTC day and the number of requests served that day";
+        readonly columns: readonly ["day", "is_bot"];
+        readonly binds: readonly ["from", "to", "include_bots"];
+        readonly resultColumns: readonly ["day", "views"];
+        readonly literals: readonly [];
+        readonly sql: SqlText;
+    };
+    readonly 'top-paths': {
+        readonly rowMeaning: "one request path and the number of requests for it over the range";
+        readonly columns: readonly ["day", "uri", "is_bot"];
+        readonly binds: readonly ["from", "to", "include_bots"];
+        readonly resultColumns: readonly ["uri", "views"];
+        readonly literals: readonly [];
+        readonly sql: SqlText;
+    };
+    readonly referrers: {
+        readonly rowMeaning: "one referring URL and the number of requests it sent over the range";
+        readonly columns: readonly ["day", "referrer", "is_bot"];
+        readonly binds: readonly ["from", "to", "include_bots"];
+        readonly resultColumns: readonly ["referrer", "views"];
+        readonly literals: readonly [];
+        readonly sql: SqlText;
+    };
+    readonly countries: {
+        readonly rowMeaning: "one viewer country and the number of requests from it over the range";
+        readonly columns: readonly ["day", "country", "is_bot"];
+        readonly binds: readonly ["from", "to", "include_bots"];
+        readonly resultColumns: readonly ["country", "views"];
+        readonly literals: readonly [];
+        readonly sql: SqlText;
+    };
+    readonly 'status-codes': {
+        readonly rowMeaning: "one HTTP status code and the number of responses carrying it over the range";
+        readonly columns: readonly ["day", "status", "is_bot"];
+        readonly binds: readonly ["from", "to", "include_bots"];
+        readonly resultColumns: readonly ["status", "views"];
+        readonly literals: readonly [];
+        readonly sql: SqlText;
+    };
+    readonly 'cache-hit-ratio': {
+        readonly rowMeaning: "one UTC day, its requests, the edge cache hits among them, and hits divided by requests";
+        readonly columns: readonly ["day", "result_type", "is_bot"];
+        readonly binds: readonly ["from", "to", "include_bots"];
+        readonly resultColumns: readonly ["day", "requests", "cache_hits", "cache_hit_ratio"];
+        readonly literals: readonly ["Hit", "RefreshHit"];
+        readonly sql: SqlText;
+    };
+    readonly 'unique-visitors': {
+        readonly 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";
+        readonly columns: readonly ["day", "visitor_key", "is_bot"];
+        readonly binds: readonly ["from", "to", "include_bots"];
+        readonly resultColumns: readonly ["day", "daily_unique_visitors", "summed_daily_unique_visitors"];
+        readonly literals: readonly [];
+        readonly sql: SqlText;
+    };
+    /**
+     * 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`.
+     */
+    readonly "row-count": {
+        readonly rowMeaning: "the number of rows the table holds over the range, one row carrying the count";
+        readonly columns: readonly ["day", "is_bot"];
+        readonly binds: readonly ["from", "to", "include_bots"];
+        readonly resultColumns: readonly ["row_count"];
+        readonly literals: readonly [];
+        readonly sql: SqlText;
+    };
+};
+/** The name of one of the {@link ANALYTICS_QUERIES}. */
+export type QueryName = keyof typeof ANALYTICS_QUERIES;
+/**
+ * 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 declare const ANALYTICS_QUERY_NAMES: readonly QueryName[];
+/**
+ * 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 declare function queryDefinition(name: string): QueryDefinition;
+/** A named query resolved against its caller's parameters, ready for an adapter to execute. */
+export interface PreparedQuery {
+    /** The name that resolved. */
+    readonly name: QueryName;
+    /** The statement to execute, exactly as its definition carries it. */
+    readonly sql: string;
+    /** The columns a row of the result carries. */
+    readonly resultColumns: readonly string[];
+    /** One entry per placeholder the statement carries, keyed by placeholder name. */
+    readonly bindings: Readonly<Record<string, BindValue>>;
+}
+/**
+ * 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 declare function prepareQuery(name: string, params: QueryParams, config: Pick<AnalyticsConfig, 'bots'>): PreparedQuery;
+export {};