@knowledgefutures/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Knowledge Futures, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @knowledgefutures/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Clients for the services a [Knowledge Futures Console](https://console.knowledgefutures.org)
+project declares, with nothing to configure: the console writes each service's
+binding into every environment that declares it, and `kf dev` writes the same
+variables pointing at local stand-ins.
+
+```sh
+npm i @knowledgefutures/sdk
+```
+
+```ts
+import { storage } from '@knowledgefutures/sdk/storage' // kf/storage@1
+await storage.put('covers/1.jpg', bytes, { contentType: 'image/jpeg' })
+
+// In tests, an in-memory store with the same interface:
+import { memoryStorage } from '@knowledgefutures/sdk/storage/testing'
+```
+
+`createStorage(env)` builds a client from an explicit environment, such as a
+Worker's `env` when `nodejs_compat` is off.
+
+What a project declares and what the services give it:
+[console.knowledgefutures.org/llms.txt](https://console.knowledgefutures.org/llms.txt).
+Source: `packages/sdk/` in [knowledgefutures/kf-console](https://github.com/knowledgefutures/kf-console).

package/dist/analytics/beacon.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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

@@ -0,0 +1,86 @@
+/**
+ * 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

@@ -0,0 +1,24 @@
+/**
+ * `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

@@ -0,0 +1,46 @@
+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

@@ -0,0 +1,10 @@
+/**
+ * `@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

@@ -0,0 +1,10 @@
+/**
+ * `@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

@@ -0,0 +1,96 @@
+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

@@ -0,0 +1,213 @@
+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;
+}