@knowledgefutures/sdk 0.1.0 → 0.2.1

package/dist/whistle/wire.js

@@ -0,0 +1,98 @@
+/**
+ * The wire format: one JSON object per event, the same on every runtime.
+ *
+ * Sent to Whistle's `/v1/events` as NDJSON, or written as the body of a
+ * `console.log`/`console.error` line. Box agents send the same objects.
+ * Whistle parses it with `parseWire`, so this file is the contract between
+ * apps and Whistle; kf-whistle's `packages/telemetry/src/wire.ts` must say
+ * the same until Whistle imports it from here.
+ */
+/** Security events: what a careful attacker can't avoid causing. Add kinds here, nowhere else. */
+export const SECURITY_KINDS = [
+    'auth.failed',
+    'auth.success',
+    'auth.mfa_failed',
+    'auth.reset_requested',
+    'token.created',
+    'token.used_new_ip',
+    'access.denied',
+    'admin.action',
+    'secret.read',
+    'member.added',
+    'export.large',
+    // From box agents (vector/vector.toml), not app code.
+    'ssh.failed',
+    'ssh.success',
+    'sudo',
+];
+const MAX_DETAIL_BYTES = 8_000;
+const SENSITIVE_KEY = /pass(word)?|secret|token|cookie|authorization|api[-_]?key|session/i;
+/**
+ * `detail` without anything that looks like a credential, and bounded in size.
+ * Apps pass objects they didn't fully build (a request's params, an error's
+ * cause), so this is the last line before a secret ends up in the lake.
+ */
+export function scrub(detail) {
+    if (!detail)
+        return undefined;
+    const walk = (value, depth) => {
+        if (depth > 4)
+            return '[depth]';
+        if (Array.isArray(value))
+            return value.slice(0, 50).map((v) => walk(v, depth + 1));
+        if (value && typeof value === 'object') {
+            const out = {};
+            for (const [k, v] of Object.entries(value)) {
+                out[k] = SENSITIVE_KEY.test(k) ? '[redacted]' : walk(v, depth + 1);
+            }
+            return out;
+        }
+        if (typeof value === 'string' && value.length > 2_000)
+            return `${value.slice(0, 2_000)}…`;
+        // JSON.stringify throws on a bigint.
+        if (typeof value === 'bigint')
+            return value.toString();
+        return value;
+    };
+    const out = walk(detail, 0);
+    if (JSON.stringify(out).length > MAX_DETAIL_BYTES)
+        return { truncated: true };
+    return out;
+}
+const isString = (v) => typeof v === 'string' && v.length > 0;
+const KINDS = new Set(SECURITY_KINDS);
+/**
+ * A wire event from a log body (a JSON string or an already-parsed object), or
+ * null when it isn't one. Tolerant of extra fields; strict about the ones rules
+ * depend on, so a malformed event never matches a rule by accident.
+ */
+export function parseWire(input) {
+    let value = input;
+    if (typeof value === 'string') {
+        const s = value.trim();
+        if (!s.startsWith('{') || !s.includes('"kf"'))
+            return null;
+        try {
+            value = JSON.parse(s);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!value || typeof value !== 'object')
+        return null;
+    const o = value;
+    if (o.v !== 1 || !isString(o.project) || !isString(o.environment) || !isString(o.at))
+        return null;
+    if (o.kf === 'security') {
+        if (!isString(o.kind) || !KINDS.has(o.kind))
+            return null;
+        return o;
+    }
+    if (o.kf === 'error') {
+        if (!isString(o.type) || typeof o.message !== 'string')
+            return null;
+        return o;
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowledgefutures/sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Zero-config clients for Knowledge Futures platform services, configured by the console.",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,10 @@
     "./storage/testing": {
       "types": "./dist/storage/testing.d.ts",
       "default": "./dist/storage/testing.js"
+    },
+    "./whistle": {
+      "types": "./dist/whistle/index.d.ts",
+      "default": "./dist/whistle/index.js"
     }
   },
   "publishConfig": {

package/dist/analytics/beacon.d.ts

@@ -1,25 +0,0 @@
-/**
- * The page script, served by the collector at `/v1/b.js`. Every project loads
- * the same line:
- *
- *   <script src="https://<collector>/v1/b.js" defer></script>
- *
- * and a project whose domains the console can't list (PubPub's custom
- * domains) adds `data-site="<site id>"`. Ported from the mitp-oecs beacon;
- * three changes: it posts to wherever it was loaded from, it sends
- * `text/plain` (so a cross-origin `sendBeacon` needs no preflight and still
- * carries `Origin`, which is how the collector attributes it), and it reads
- * `kf:scope`.
- *
- * What a page declares, the beacon reads:
- *
- *   <meta name="kf:subject" content="pub:za65x7nh">
- *   <meta name="kf:subject-uri" content="https://doi.org/10.21428/…">
- *   <meta name="kf:scope" content="<community id>">
- *
- * One view per page load; `data-kf-event="download:pdf"` on any element
- * reports that event on click; `window.kf.track(kind, name, props)` for the
- * rest. No cookies, no storage, nothing about the reader beyond the referrer.
- * Every failure is swallowed: analytics must never break a page.
- */
-export declare const BEACON_JS = "(() => {\n  try {\n    const script = document.currentScript;\n    if (!script || !script.src) return;\n    const endpoint = new URL('e', script.src);\n    const site = script.getAttribute('data-site');\n    if (site) endpoint.searchParams.set('site', site);\n    const EP = endpoint.toString();\n    const meta = (n) => {\n      const el = document.querySelector('meta[name=\"' + n + '\"]');\n      return (el && el.getAttribute('content')) || undefined;\n    };\n    let utm;\n    new URLSearchParams(location.search).forEach((v, k) => {\n      const key = k.indexOf('utm_') === 0 ? k.slice(4) : '';\n      if (v && ['source', 'medium', 'campaign', 'term', 'content'].indexOf(key) >= 0) {\n        (utm = utm || {})[key] = String(v);\n      }\n    });\n    const strs = (o) => {\n      if (!o || typeof o !== 'object') return undefined;\n      const out = {};\n      let n = 0;\n      for (const k in o) if (o[k] !== undefined && o[k] !== null) { out[k] = String(o[k]); n++; }\n      return n ? out : undefined;\n    };\n    const send = (kind, name, props) => {\n      try {\n        const body = {\n          kind: kind,\n          subject: meta('kf:subject'),\n          subjectUri: meta('kf:subject-uri'),\n          scope: meta('kf:scope'),\n          path: location.pathname,\n          referrer: document.referrer || undefined,\n          name: (typeof name === 'string' && name) || undefined,\n          props: strs(props),\n          utm: utm,\n        };\n        for (const k in body) if (body[k] === undefined) delete body[k];\n        const json = JSON.stringify(body);\n        if (navigator.sendBeacon && navigator.sendBeacon(EP, json)) return;\n        fetch(EP, { method: 'POST', mode: 'no-cors', keepalive: true, credentials: 'omit',\n          headers: { 'content-type': 'text/plain' }, body: json });\n      } catch (e) {}\n    };\n    window.kf = { track: send };\n    const view = () => send('view');\n    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', view, { once: true });\n    else view();\n    document.addEventListener('click', (e) => {\n      try {\n        const el = e.target && e.target.closest && e.target.closest('[data-kf-event]');\n        if (!el) return;\n        const parts = (el.getAttribute('data-kf-event') || '').split(':');\n        const kind = parts.shift();\n        if (kind) send(kind, parts.join(':'));\n      } catch (err) {}\n    }, true);\n  } catch (e) {}\n})();\n";

package/dist/analytics/beacon.js

@@ -1,86 +0,0 @@
-/**
- * The page script, served by the collector at `/v1/b.js`. Every project loads
- * the same line:
- *
- *   <script src="https://<collector>/v1/b.js" defer></script>
- *
- * and a project whose domains the console can't list (PubPub's custom
- * domains) adds `data-site="<site id>"`. Ported from the mitp-oecs beacon;
- * three changes: it posts to wherever it was loaded from, it sends
- * `text/plain` (so a cross-origin `sendBeacon` needs no preflight and still
- * carries `Origin`, which is how the collector attributes it), and it reads
- * `kf:scope`.
- *
- * What a page declares, the beacon reads:
- *
- *   <meta name="kf:subject" content="pub:za65x7nh">
- *   <meta name="kf:subject-uri" content="https://doi.org/10.21428/…">
- *   <meta name="kf:scope" content="<community id>">
- *
- * One view per page load; `data-kf-event="download:pdf"` on any element
- * reports that event on click; `window.kf.track(kind, name, props)` for the
- * rest. No cookies, no storage, nothing about the reader beyond the referrer.
- * Every failure is swallowed: analytics must never break a page.
- */
-export const BEACON_JS = `(() => {
-  try {
-    const script = document.currentScript;
-    if (!script || !script.src) return;
-    const endpoint = new URL('e', script.src);
-    const site = script.getAttribute('data-site');
-    if (site) endpoint.searchParams.set('site', site);
-    const EP = endpoint.toString();
-    const meta = (n) => {
-      const el = document.querySelector('meta[name="' + n + '"]');
-      return (el && el.getAttribute('content')) || undefined;
-    };
-    let utm;
-    new URLSearchParams(location.search).forEach((v, k) => {
-      const key = k.indexOf('utm_') === 0 ? k.slice(4) : '';
-      if (v && ['source', 'medium', 'campaign', 'term', 'content'].indexOf(key) >= 0) {
-        (utm = utm || {})[key] = String(v);
-      }
-    });
-    const strs = (o) => {
-      if (!o || typeof o !== 'object') return undefined;
-      const out = {};
-      let n = 0;
-      for (const k in o) if (o[k] !== undefined && o[k] !== null) { out[k] = String(o[k]); n++; }
-      return n ? out : undefined;
-    };
-    const send = (kind, name, props) => {
-      try {
-        const body = {
-          kind: kind,
-          subject: meta('kf:subject'),
-          subjectUri: meta('kf:subject-uri'),
-          scope: meta('kf:scope'),
-          path: location.pathname,
-          referrer: document.referrer || undefined,
-          name: (typeof name === 'string' && name) || undefined,
-          props: strs(props),
-          utm: utm,
-        };
-        for (const k in body) if (body[k] === undefined) delete body[k];
-        const json = JSON.stringify(body);
-        if (navigator.sendBeacon && navigator.sendBeacon(EP, json)) return;
-        fetch(EP, { method: 'POST', mode: 'no-cors', keepalive: true, credentials: 'omit',
-          headers: { 'content-type': 'text/plain' }, body: json });
-      } catch (e) {}
-    };
-    window.kf = { track: send };
-    const view = () => send('view');
-    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', view, { once: true });
-    else view();
-    document.addEventListener('click', (e) => {
-      try {
-        const el = e.target && e.target.closest && e.target.closest('[data-kf-event]');
-        if (!el) return;
-        const parts = (el.getAttribute('data-kf-event') || '').split(':');
-        const kind = parts.shift();
-        if (kind) send(kind, parts.join(':'));
-      } catch (err) {}
-    }, true);
-  } catch (e) {}
-})();
-`;

package/dist/analytics/binding.d.ts

@@ -1,24 +0,0 @@
-/**
- * `KF_ANALYTICS_URL` — the whole contract between the console, which
- * registers a site with the collector and writes the binding into a
- * project's environment, and the SDK, which reads it. Both import this file,
- * so the format has exactly one definition.
- *
- *   https://<site>:<secret>@<collector host>[/<base path>]
- *
- * `http` only for a local collector. The site id is public (a keyed beacon
- * carries it); the secret signs server events and queries, and never reaches
- * a browser. `log:` is `kf dev`'s binding: events are printed, nothing is
- * sent.
- */
-export interface AnalyticsBinding {
-    /** The collector's origin and base path, no trailing slash. */
-    endpoint: string;
-    site: string;
-    secret: string;
-}
-export declare const ANALYTICS_ENV = "KF_ANALYTICS_URL";
-export declare const LOG_BINDING = "log:";
-export declare function encodeAnalyticsBinding(b: AnalyticsBinding): string;
-/** The binding, or `'log'` for `kf dev`'s print-only binding. */
-export declare function decodeAnalyticsBinding(value: string): AnalyticsBinding | 'log';

package/dist/analytics/binding.js

@@ -1,46 +0,0 @@
-import { AnalyticsError } from './errors.js';
-export const ANALYTICS_ENV = 'KF_ANALYTICS_URL';
-export const LOG_BINDING = 'log:';
-const SITE = /^[A-Za-z0-9_-]{1,64}$/;
-export function encodeAnalyticsBinding(b) {
-    const endpoint = new URL(b.endpoint);
-    if (endpoint.protocol !== 'https:' && endpoint.protocol !== 'http:') {
-        throw new AnalyticsError('invalid', `endpoint must be http(s): ${b.endpoint}`);
-    }
-    if (!SITE.test(b.site))
-        throw new AnalyticsError('invalid', `not a site id: ${b.site}`);
-    if (!b.secret)
-        throw new AnalyticsError('invalid', 'the secret is empty');
-    const path = endpoint.pathname.replace(/\/+$/, '');
-    return `${endpoint.protocol}//${b.site}:${encodeURIComponent(b.secret)}@${endpoint.host}${path}`;
-}
-/** The binding, or `'log'` for `kf dev`'s print-only binding. */
-export function decodeAnalyticsBinding(value) {
-    const v = value.trim();
-    if (v === LOG_BINDING)
-        return 'log';
-    let url;
-    try {
-        url = new URL(v);
-    }
-    catch {
-        throw bad('not a URL');
-    }
-    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
-        throw bad(`the scheme is https (or http for a local collector), or the value is "${LOG_BINDING}"`);
-    }
-    const site = decodeURIComponent(url.username);
-    if (!SITE.test(site))
-        throw bad('the user part is the site id');
-    if (!url.password)
-        throw bad('the secret is missing');
-    return {
-        endpoint: `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, '')}`,
-        site,
-        secret: decodeURIComponent(url.password),
-    };
-}
-function bad(why) {
-    // Never echo the value: it carries the secret.
-    return new AnalyticsError('not_configured', `${ANALYTICS_ENV} is malformed: ${why}`);
-}

package/dist/analytics/collector.d.ts

@@ -1,10 +0,0 @@
-/**
- * `@knowledgefutures/sdk/analytics/collector` — what the `kf/analytics`
- * collector imports: the event format, the query semantics and the page
- * script. The SDK's client half uses the same files, which is the point:
- * a hint the SDK accepts is a hint the collector accepts, and a query answers
- * the same from the memory double as from the service.
- */
-export { buildRow, device, FIELDS, KINDS, LIMITS, SCHEMA, UTM_KEYS, validateHint, type Device, type EventRow, type Hint, type Kind, type RowContext, type ServerHint, type Source, } from './envelope.js';
-export { CUBES, cubeRows, MAX_ROWS, runQuery, validateQuery, type Cube, type CubeRow, type Query, type QueryResult, } from './cubes.js';
-export { BEACON_JS } from './beacon.js';

package/dist/analytics/collector.js

@@ -1,10 +0,0 @@
-/**
- * `@knowledgefutures/sdk/analytics/collector` — what the `kf/analytics`
- * collector imports: the event format, the query semantics and the page
- * script. The SDK's client half uses the same files, which is the point:
- * a hint the SDK accepts is a hint the collector accepts, and a query answers
- * the same from the memory double as from the service.
- */
-export { buildRow, device, FIELDS, KINDS, LIMITS, SCHEMA, UTM_KEYS, validateHint, } from './envelope.js';
-export { CUBES, cubeRows, MAX_ROWS, runQuery, validateQuery, } from './cubes.js';
-export { BEACON_JS } from './beacon.js';

package/dist/analytics/cubes.d.ts

@@ -1,96 +0,0 @@
-import type { EventRow } from './envelope.js';
-/**
- * The cubes: one site's events, collapsed into daily rows the compactor
- * writes and every query reads. They are OECS's eleven summary files
- * generalized — `pubs` and `collections` became `subjects`, keyed by
- * `subject_type`, and every cube gains `scope`.
- *
- * Two rules hold everywhere:
- *
- * - **Bots are gone** (`device = 'bot'`) before anything is counted.
- * - **Every metric is a count, so it sums across days.** A query over any
- *   range is a sum of daily rows, and exact. A metric that can't be summed —
- *   distinct subjects in a month, unique people — can never be a column.
- *
- * `views` are rows with `kind = 'view'`; `visits` are views with
- * `is_unique` (the referrer heuristic: visits, never "unique visitors").
- *
- * `cubeRows` is the reference implementation, used by the memory double.
- * The compactor computes the same rows in SQL, and the conformance suite
- * holds the two to each other.
- */
-export declare const CUBES: {
-    readonly days: {
-        readonly dims: readonly ["day", "scope"];
-        readonly metrics: readonly ["views", "visits", "downloads", "searches", "custom"];
-    };
-    readonly subjects: {
-        readonly dims: readonly ["day", "scope", "subject_type", "subject_id"];
-        readonly metrics: readonly ["views", "visits", "downloads"];
-    };
-    readonly pages: {
-        readonly dims: readonly ["day", "scope", "path"];
-        readonly metrics: readonly ["views", "visits"];
-    };
-    readonly referrers: {
-        readonly dims: readonly ["day", "scope", "referrer_host"];
-        readonly metrics: readonly ["views", "visits"];
-    };
-    readonly campaigns: {
-        readonly dims: readonly ["day", "scope", "utm_source", "utm_medium", "utm_campaign"];
-        readonly metrics: readonly ["views", "visits"];
-    };
-    readonly devices: {
-        readonly dims: readonly ["day", "scope", "device"];
-        readonly metrics: readonly ["views", "visits"];
-    };
-    readonly countries: {
-        readonly dims: readonly ["day", "scope", "country"];
-        readonly metrics: readonly ["views", "visits"];
-    };
-    readonly downloads: {
-        readonly dims: readonly ["day", "scope", "subject_type", "subject_id", "name"];
-        readonly metrics: readonly ["downloads"];
-    };
-    readonly searches: {
-        readonly dims: readonly ["day", "scope", "name"];
-        readonly metrics: readonly ["searches"];
-    };
-};
-export type Cube = keyof typeof CUBES;
-export type Dim<C extends Cube = Cube> = (typeof CUBES)[C]['dims'][number];
-export type Metric<C extends Cube = Cube> = (typeof CUBES)[C]['metrics'][number];
-/** A cube row: its dimensions (null where the event had none) and its counts. */
-export type CubeRow = Record<string, string | number | null>;
-/** One cube's daily rows from raw events, sorted by day. The compactor's contract, in code. */
-export declare function cubeRows(cube: Cube, events: readonly EventRow[]): CubeRow[];
-export interface Query<C extends Cube = Cube> {
-    cube: C;
-    /** First closed UTC day, inclusive, `YYYY-MM-DD`. */
-    from: string;
-    /** Last closed UTC day, inclusive. */
-    to: string;
-    /** Equality on a dimension; an array is "any of". `null` matches rows without the dimension. */
-    filter?: Partial<Record<Dim<C>, string | null | ReadonlyArray<string | null>>>;
-    /** The dimensions to keep. Omitted or `[]`: one row of totals. */
-    groupBy?: ReadonlyArray<Dim<C>>;
-    /** A metric or dimension, `-` first for descending. Default: the group's dimensions, ascending. */
-    order?: string;
-    /** At most `MAX_ROWS`. */
-    limit?: number;
-    /** Another of the project's environments. Default: the caller's own. */
-    environment?: string;
-}
-export interface QueryResult {
-    rows: CubeRow[];
-    /** The last day the cubes cover, or null when the site has no data yet. Today is never in them. */
-    through: string | null;
-}
-export declare const MAX_ROWS = 10000;
-/** Why a query is refused, or null. The collector runs this too, so both answer alike. */
-export declare function validateQuery(q: unknown): string | null;
-/**
- * Answer a query from a cube's daily rows: keep the range and the filter,
- * group, sum, sort, cut. Throws `invalid` for a query `validateQuery` refuses.
- */
-export declare function runQuery(rows: readonly CubeRow[], q: Query): CubeRow[];

package/dist/analytics/cubes.js

@@ -1,213 +0,0 @@
-import { AnalyticsError } from './errors.js';
-/**
- * The cubes: one site's events, collapsed into daily rows the compactor
- * writes and every query reads. They are OECS's eleven summary files
- * generalized — `pubs` and `collections` became `subjects`, keyed by
- * `subject_type`, and every cube gains `scope`.
- *
- * Two rules hold everywhere:
- *
- * - **Bots are gone** (`device = 'bot'`) before anything is counted.
- * - **Every metric is a count, so it sums across days.** A query over any
- *   range is a sum of daily rows, and exact. A metric that can't be summed —
- *   distinct subjects in a month, unique people — can never be a column.
- *
- * `views` are rows with `kind = 'view'`; `visits` are views with
- * `is_unique` (the referrer heuristic: visits, never "unique visitors").
- *
- * `cubeRows` is the reference implementation, used by the memory double.
- * The compactor computes the same rows in SQL, and the conformance suite
- * holds the two to each other.
- */
-export const CUBES = {
-    days: { dims: ['day', 'scope'], metrics: ['views', 'visits', 'downloads', 'searches', 'custom'] },
-    subjects: {
-        dims: ['day', 'scope', 'subject_type', 'subject_id'],
-        metrics: ['views', 'visits', 'downloads'],
-    },
-    pages: { dims: ['day', 'scope', 'path'], metrics: ['views', 'visits'] },
-    referrers: { dims: ['day', 'scope', 'referrer_host'], metrics: ['views', 'visits'] },
-    campaigns: {
-        dims: ['day', 'scope', 'utm_source', 'utm_medium', 'utm_campaign'],
-        metrics: ['views', 'visits'],
-    },
-    devices: { dims: ['day', 'scope', 'device'], metrics: ['views', 'visits'] },
-    countries: { dims: ['day', 'scope', 'country'], metrics: ['views', 'visits'] },
-    downloads: {
-        dims: ['day', 'scope', 'subject_type', 'subject_id', 'name'],
-        metrics: ['downloads'],
-    },
-    searches: { dims: ['day', 'scope', 'name'], metrics: ['searches'] },
-};
-/** Which events a cube counts, beyond "not a bot". */
-const KEEP = {
-    days: () => true,
-    subjects: (e) => e.subject_type !== null && (e.kind === 'view' || e.kind === 'download'),
-    pages: (e) => e.kind === 'view',
-    // External referrers only: a click from one page of the site to another is not a referral.
-    referrers: (e) => e.kind === 'view' && e.referrer_host !== null && e.referrer_host !== e.hostname,
-    campaigns: (e) => e.kind === 'view' &&
-        (e.utm_source !== null || e.utm_medium !== null || e.utm_campaign !== null),
-    devices: (e) => e.kind === 'view',
-    countries: (e) => e.kind === 'view',
-    downloads: (e) => e.kind === 'download',
-    searches: (e) => e.kind === 'search',
-};
-function counts(e) {
-    return {
-        views: e.kind === 'view' ? 1 : 0,
-        visits: e.kind === 'view' && e.is_unique ? 1 : 0,
-        downloads: e.kind === 'download' ? 1 : 0,
-        searches: e.kind === 'search' ? 1 : 0,
-        custom: e.kind === 'custom' ? 1 : 0,
-    };
-}
-/** One cube's daily rows from raw events, sorted by day. The compactor's contract, in code. */
-export function cubeRows(cube, events) {
-    const { dims, metrics } = CUBES[cube];
-    const keep = KEEP[cube];
-    const rows = new Map();
-    for (const e of events) {
-        if (e.device === 'bot' || !keep(e))
-            continue;
-        const key = JSON.stringify(dims.map((d) => e[d]));
-        let row = rows.get(key);
-        if (!row) {
-            row = Object.fromEntries([
-                ...dims.map((d) => [d, e[d]]),
-                ...metrics.map((m) => [m, 0]),
-            ]);
-            rows.set(key, row);
-        }
-        const c = counts(e);
-        for (const m of metrics)
-            row[m] = row[m] + c[m];
-    }
-    return [...rows.values()].sort((a, b) => String(a.day).localeCompare(String(b.day)));
-}
-export const MAX_ROWS = 10_000;
-const DAY = /^\d{4}-\d{2}-\d{2}$/;
-/** Why a query is refused, or null. The collector runs this too, so both answer alike. */
-export function validateQuery(q) {
-    if (!q || typeof q !== 'object' || Array.isArray(q))
-        return 'query must be an object';
-    const query = q;
-    const known = new Set([
-        'cube',
-        'from',
-        'to',
-        'filter',
-        'groupBy',
-        'order',
-        'limit',
-        'environment',
-    ]);
-    for (const key of Object.keys(query))
-        if (!known.has(key))
-            return `unknown key "${key}"`;
-    if (typeof query.cube !== 'string' || !Object.hasOwn(CUBES, query.cube)) {
-        return `cube must be one of ${Object.keys(CUBES).join(', ')}`;
-    }
-    const { dims, metrics } = CUBES[query.cube];
-    const isDim = (d) => dims.includes(d);
-    for (const key of ['from', 'to']) {
-        const v = query[key];
-        if (typeof v !== 'string' || !DAY.test(v) || Number.isNaN(Date.parse(v))) {
-            return `${key} must be a day, YYYY-MM-DD`;
-        }
-    }
-    if (query.from > query.to)
-        return 'from is after to';
-    if (query.filter !== undefined) {
-        if (!query.filter || typeof query.filter !== 'object' || Array.isArray(query.filter)) {
-            return 'filter must be an object';
-        }
-        for (const [d, v] of Object.entries(query.filter)) {
-            if (!isDim(d))
-                return `${query.cube} has no dimension "${d}"; it has ${dims.join(', ')}`;
-            const values = Array.isArray(v) ? v : [v];
-            if (values.some((x) => x !== null && typeof x !== 'string')) {
-                return `filter.${d} must be a string, null, or a list of them`;
-            }
-        }
-    }
-    if (query.groupBy !== undefined) {
-        if (!Array.isArray(query.groupBy))
-            return 'groupBy must be a list';
-        for (const d of query.groupBy) {
-            if (!isDim(d))
-                return `${query.cube} has no dimension "${String(d)}"; it has ${dims.join(', ')}`;
-        }
-    }
-    if (query.order !== undefined) {
-        const field = typeof query.order === 'string' ? query.order.replace(/^-/, '') : undefined;
-        const grouped = query.groupBy ?? [];
-        if (!field || !(metrics.includes(field) || grouped.includes(field))) {
-            return 'order must be a metric or a grouped dimension, "-" first for descending';
-        }
-    }
-    if (query.limit !== undefined) {
-        const n = query.limit;
-        if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > MAX_ROWS) {
-            return `limit must be a whole number from 1 to ${MAX_ROWS}`;
-        }
-    }
-    if (query.environment !== undefined && typeof query.environment !== 'string') {
-        return 'environment must be a string';
-    }
-    return null;
-}
-/**
- * Answer a query from a cube's daily rows: keep the range and the filter,
- * group, sum, sort, cut. Throws `invalid` for a query `validateQuery` refuses.
- */
-export function runQuery(rows, q) {
-    const problem = validateQuery(q);
-    if (problem)
-        throw new AnalyticsError('invalid', problem);
-    const { metrics } = CUBES[q.cube];
-    const groupBy = [...(q.groupBy ?? [])];
-    const filter = Object.entries(q.filter ?? {}).map(([d, v]) => [d, Array.isArray(v) ? v : [v]]);
-    const groups = new Map();
-    for (const row of rows) {
-        const day = String(row.day);
-        if (day < q.from || day > q.to)
-            continue;
-        if (!filter.every(([d, values]) => values.includes(row[d] ?? null)))
-            continue;
-        const key = JSON.stringify(groupBy.map((d) => row[d] ?? null));
-        let out = groups.get(key);
-        if (!out) {
-            out = Object.fromEntries([
-                ...groupBy.map((d) => [d, row[d] ?? null]),
-                ...metrics.map((m) => [m, 0]),
-            ]);
-            groups.set(key, out);
-        }
-        for (const m of metrics)
-            out[m] = out[m] + Number(row[m] ?? 0);
-    }
-    let out = [...groups.values()];
-    // Totals over an empty range are still one row of zeros, so a caller can read `rows[0].views`.
-    if (out.length === 0 && groupBy.length === 0) {
-        out = [Object.fromEntries(metrics.map((m) => [m, 0]))];
-    }
-    const order = q.order ?? groupBy[0];
-    if (order) {
-        const desc = order.startsWith('-');
-        const field = desc ? order.slice(1) : order;
-        out.sort((a, b) => compare(a[field] ?? null, b[field] ?? null, desc));
-    }
-    return out.slice(0, q.limit ?? MAX_ROWS);
-}
-/** Nulls last either way; numbers numerically, strings by code point (so days sort as days). */
-function compare(a, b, desc) {
-    if (a === b)
-        return 0;
-    if (a === null)
-        return 1;
-    if (b === null)
-        return -1;
-    const c = typeof a === 'number' && typeof b === 'number' ? a - b : String(a) < String(b) ? -1 : 1;
-    return desc ? -c : c;
-}