@gscdump/engine 0.7.1 → 0.7.3

package/README.md

@@ -61,7 +61,7 @@ Optional peers (install only what your runtime needs):
 - [`gscdump`](../gscdump) — REST client + query builder (edge-safe peer dep).
 - [`@gscdump/analysis`](../analysis) — analyzers; consumes `StorageEngine` via `createEngine` factories.
 - [`@gscdump/engine-duckdb-node`](../engine-duckdb-node) — Node DuckDB analyzer adapter.
-- [`@gscdump/engine-wasm`](../engine-wasm) — DuckDB-WASM browser adapter.
+- [`@gscdump/engine-duckdb-wasm`](../engine-duckdb-wasm) — DuckDB-WASM browser adapter.
 - [`@gscdump/engine-sqlite`](../engine-sqlite) — SQLite / D1 adapter.
 - [`@gscdump/cli`](../cli) — CLI wrapping engine + analysis.
 

package/dist/_chunks/analysis-types.d.mts

@@ -0,0 +1,47 @@
+import { BuilderState } from "gscdump/query";
+type AnalysisTool = 'striking-distance' | 'opportunity' | 'movers' | 'decay' | 'zero-click' | 'brand' | 'cannibalization' | 'clustering' | 'concentration' | 'seasonality' | 'trends' | 'ctr-anomaly' | 'position-volatility' | 'long-tail' | 'intent-atlas' | 'query-migration' | 'bayesian-ctr' | 'stl-decompose' | 'change-point' | 'bipartite-pagerank' | 'survival' | 'position-distribution' | 'ctr-curve' | 'dark-traffic' | 'content-velocity' | 'keyword-breadth' | 'device-gap' | 'data-query' | 'data-detail';
+interface AnalysisParams {
+  type: AnalysisTool;
+  startDate?: string;
+  endDate?: string;
+  prevStartDate?: string;
+  prevEndDate?: string;
+  brandTerms?: string[];
+  limit?: number;
+  offset?: number;
+  /** Sort column. Each analyzer enforces its own whitelist. */
+  sortBy?: string;
+  /** Sort direction. Default per-analyzer. */
+  sortDir?: 'asc' | 'desc';
+  minPosition?: number;
+  maxPosition?: number;
+  minImpressions?: number;
+  maxCtr?: number;
+  minPages?: number;
+  maxPositionSpread?: number;
+  minClusterSize?: number;
+  clusterBy?: 'prefix' | 'intent' | 'both';
+  dimension?: 'pages' | 'keywords';
+  topN?: number;
+  metric?: 'clicks' | 'impressions';
+  changeThreshold?: number;
+  minPreviousClicks?: number;
+  threshold?: number;
+  weeks?: number;
+  minWeeksWithData?: number;
+  /** content-velocity lookback window in days (max 365, default 90). */
+  days?: number;
+  /** data-query / data-detail primary BuilderState. */
+  q?: BuilderState;
+  /** data-query / data-detail optional comparison-period BuilderState. */
+  qc?: BuilderState;
+  /** data-query comparison filter applied to joined current/previous rows. */
+  comparisonFilter?: 'new' | 'lost' | 'improving' | 'declining';
+}
+interface AnalysisResult {
+  results: Record<string, unknown>[];
+  meta: Record<string, unknown>;
+}
+/** Coerce arbitrary value (number, bigint, string, null) to number, defaulting to 0. */
+declare function num(v: unknown): number;
+export { num as i, AnalysisResult as n, AnalysisTool as r, AnalysisParams as t };

package/dist/_chunks/contracts.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/_chunks/dispatch.mjs

@@ -0,0 +1,75 @@
+var AnalyzerCapabilityError = class extends Error {
+	constructor(tool, missing) {
+		super(`analyzer "${tool}" requires capabilities [${missing.join(", ")}] not provided by source`);
+		this.tool = tool;
+		this.missing = missing;
+		this.name = "AnalyzerCapabilityError";
+	}
+};
+function sourceCapabilities(source) {
+	const caps = /* @__PURE__ */ new Set();
+	if (source.executeSql) caps.add("executeSql");
+	if (source.capabilities.fileSets) caps.add("partitionedParquet");
+	if (source.capabilities.regex) caps.add("regex");
+	if (source.capabilities.windowTotals) caps.add("windowTotals");
+	if (source.capabilities.comparisonJoin) caps.add("comparisonJoin");
+	if (source.capabilities.attachedTables) caps.add("attachedTables");
+	return caps;
+}
+function assertSatisfies(analyzer, caps) {
+	const missing = analyzer.requires.filter((c) => !caps.has(c));
+	if (missing.length > 0) throw new AnalyzerCapabilityError(analyzer.id, missing);
+}
+async function runAnalyzerFromSource(source, params, registry) {
+	const caps = sourceCapabilities(source);
+	const analyzer = registry.resolveAnalyzer(params.type, caps.has("executeSql") || caps.has("attachedTables"));
+	if (!analyzer) throw new AnalyzerCapabilityError(params.type, ["executeSql"]);
+	assertSatisfies(analyzer, caps);
+	const plan = analyzer.build(params);
+	if (plan.kind === "rows") return runRowsPlanAgainstSource(source, analyzer, plan, params);
+	return runSqlPlanAgainstSource(source, analyzer, plan, params);
+}
+async function runRowsPlanAgainstSource(source, analyzer, plan, params) {
+	const entries = Object.entries(plan.queries);
+	const resolved = await Promise.all(entries.map(async ([k, q]) => [k, await source.queryRows(q.state)]));
+	const rowMap = Object.fromEntries(resolved);
+	const { results, meta } = analyzer.reduce(rowMap, { params });
+	return {
+		results,
+		meta: {
+			tool: params.type,
+			...meta
+		}
+	};
+}
+function fileSetsFor(plan) {
+	const fileSets = { FILES: plan.current };
+	if (plan.previous) fileSets.FILES_PREV = plan.previous;
+	if (plan.extraFiles) for (const [key, fs] of Object.entries(plan.extraFiles)) fileSets[`FILES_${key}`] = fs;
+	return fileSets;
+}
+async function runSqlPlanAgainstSource(source, analyzer, plan, params) {
+	if (!source.executeSql) throw new AnalyzerCapabilityError(analyzer.id, ["executeSql"]);
+	if (plan.requiresAttachedTables && !source.capabilities.attachedTables) throw new AnalyzerCapabilityError(analyzer.id, ["attachedTables"]);
+	const fileSets = source.capabilities.fileSets ? fileSetsFor(plan) : void 0;
+	const rows = await source.executeSql(plan.sql, plan.params, fileSets ? { fileSets } : void 0);
+	const extras = {};
+	if (plan.extraQueries) for (const q of plan.extraQueries) {
+		const extraRows = await source.executeSql(q.sql, q.params, fileSets ? { fileSets } : void 0);
+		extras[q.name] = extraRows;
+	}
+	const { results, meta } = analyzer.reduce(rows, {
+		params,
+		extras
+	});
+	const sourceMeta = source.capabilities.localSource ? { source: "local" } : source.capabilities.attachedTables ? { source: "browser" } : {};
+	return {
+		results,
+		meta: {
+			tool: params.type,
+			...sourceMeta,
+			...meta
+		}
+	};
+}
+export { runAnalyzerFromSource as n, AnalyzerCapabilityError as t };

package/dist/_chunks/registry.d.mts

@@ -0,0 +1,92 @@
+import { w as Row } from "./storage.mjs";
+import { t as AnalysisParams } from "./analysis-types.mjs";
+import { r as FileSet } from "./source-types.mjs";
+import { BuilderState } from "gscdump/query";
+/**
+ * Capabilities a Plan may require of its host. A dispatcher matches these
+ * against a source's declared capabilities and rejects mismatches.
+ */
+type Capability = 'executeSql' | 'partitionedParquet' | 'attachedTables' | 'regex' | 'windowTotals' | 'comparisonJoin';
+interface SqlExtraQuery {
+  name: string;
+  sql: string;
+  params: unknown[];
+}
+/**
+ * SQL-native plan: SQL string + placeholders, with optional extra file sets
+ * and follow-up queries.
+ */
+interface SqlPlan {
+  kind: 'sql';
+  sql: string;
+  params: unknown[];
+  current: FileSet;
+  previous?: FileSet;
+  extraFiles?: Record<string, FileSet>;
+  extraQueries?: SqlExtraQuery[];
+  /** Emits direct table refs (browser-only). Dispatcher rejects for manifest path. */
+  requiresAttachedTables?: boolean;
+}
+interface TypedRowQuery<T extends Row = Row> {
+  state: BuilderState;
+  /** Optional type tag for downstream narrowing. */
+  rowType?: (row: Row) => T;
+}
+/**
+ * Row-queries plan: a named set of typed `BuilderState` queries. A portable
+ * dispatcher runs each against a source's `queryRows` and hands the row
+ * collection to `reduce`.
+ */
+interface RowQueriesPlan {
+  kind: 'rows';
+  queries: Record<string, TypedRowQuery>;
+}
+type Plan = SqlPlan | RowQueriesPlan;
+interface ReduceContext<TRow extends Row = Row> {
+  params: AnalysisParams;
+  /** Extra SQL-query results keyed by `SqlExtraQuery.name`. */
+  extras?: Record<string, TRow[]>;
+}
+/**
+ * Unified analyzer contract. `TRow` lets authors narrow from the default
+ * `Row = Record<string, unknown>` to a typed row shape (e.g. `KeywordRow`)
+ * when their reducer assumes specific columns exist — catches drift between
+ * `build` (SELECT list) and `reduce` (column access) at compile time.
+ */
+interface Analyzer<P extends AnalysisParams = AnalysisParams, R = unknown, TRow extends Row = Row> {
+  /** Stable tool id (e.g. `striking-distance`, `opportunity`). */
+  id: string;
+  /** Capabilities a host source must provide. */
+  requires: readonly Capability[];
+  /** Pure: params → plan. Snapshot-testable. */
+  build: (params: P) => Plan;
+  /** Pure: rows + context → typed result + meta. */
+  reduce: (rows: TRow[] | Record<string, TRow[]>, ctx: ReduceContext<TRow>) => {
+    results: R;
+    meta?: Record<string, unknown>;
+  };
+}
+interface AnalyzerVariants {
+  sql?: Analyzer;
+  rows?: Analyzer;
+}
+interface AnalyzerRegistryInit {
+  rows?: readonly Analyzer[];
+  sql?: readonly Analyzer[];
+}
+interface AnalyzerRegistry {
+  listAnalyzerIds: () => readonly string[];
+  getAnalyzerVariants: (id: string) => AnalyzerVariants | undefined;
+  resolveAnalyzer: (id: string, sourceSupportsSql: boolean) => Analyzer | undefined;
+  listAnalyzersFor: (sourceSupportsSql: boolean) => readonly Analyzer[];
+  listAnalyzerIdsFor: (source: {
+    executeSql?: unknown;
+  }) => readonly string[];
+}
+/**
+ * Build an immutable registry from collections of row / SQL analyzers.
+ * No global state; call this once per logical use (typically at startup
+ * or per-request in a worker).
+ */
+declare function createAnalyzerRegistry(init?: AnalyzerRegistryInit): AnalyzerRegistry;
+export { Analyzer as a, ReduceContext as c, SqlPlan as d, TypedRowQuery as f, createAnalyzerRegistry as i, RowQueriesPlan as l, AnalyzerRegistryInit as n, Capability as o, AnalyzerVariants as r, Plan as s, AnalyzerRegistry as t, SqlExtraQuery as u };

package/dist/_chunks/resolver.mjs

@@ -0,0 +1,91 @@
+import { t as SCHEMAS } from "./schema.mjs";
+import { _ as resolveToSQL } from "./pg-adapter.mjs";
+import { normalizeUrl } from "gscdump/normalize";
+function createSqlQuerySource(options) {
+	const { name, adapter, execute, siteId, extraCapabilities } = options;
+	return {
+		name,
+		capabilities: {
+			...adapter.capabilities,
+			...extraCapabilities
+		},
+		async queryRows(state) {
+			const resolved = resolveToSQL(state, {
+				adapter,
+				siteId
+			});
+			return execute(resolved.sql, resolved.params);
+		},
+		executeSql(sql, params) {
+			return execute(sql, params ?? []);
+		}
+	};
+}
+function collectInternalFilters(filter) {
+	if (!filter || !("_filters" in filter)) return [];
+	const flat = filter._filters;
+	const nested = filter._nestedGroups?.flatMap((group) => collectInternalFilters(group)) ?? [];
+	return [...flat, ...nested];
+}
+function getInternalFilters(filter) {
+	return collectInternalFilters(filter);
+}
+function getDimensionFilters(filter, isMetricDimension) {
+	return collectInternalFilters(filter).filter((f) => f.dimension !== "date" && !isMetricDimension(f.dimension) && f.operator !== "topLevel" && !f.operator.startsWith("metric"));
+}
+function getFilterDimensions(filter, isMetricDimension) {
+	return getDimensionFilters(filter, isMetricDimension).map((f) => f.dimension);
+}
+function metricValue(row, metric) {
+	const value = row[metric];
+	if (typeof value === "number") return value;
+	if (typeof value === "bigint") return Number(value);
+	if (value == null) return 0;
+	return Number(value);
+}
+function dimensionValue(row, dimension) {
+	const value = row[dimension];
+	return value == null ? "" : String(value);
+}
+function matchesDimensionFilter(row, filter) {
+	const raw = dimensionValue(row, filter.dimension);
+	const value = filter.dimension === "page" ? normalizeUrl(raw) : raw;
+	switch (filter.operator) {
+		case "equals": return value === filter.expression;
+		case "notEquals": return value !== filter.expression;
+		case "contains": return raw.includes(filter.expression);
+		case "notContains": return !raw.includes(filter.expression);
+		case "includingRegex": return new RegExp(filter.expression).test(raw);
+		case "excludingRegex": return !new RegExp(filter.expression).test(raw);
+		default: return true;
+	}
+}
+function matchesMetricFilter(row, filter) {
+	const value = metricValue(row, filter.dimension);
+	const target = Number(filter.expression);
+	switch (filter.operator) {
+		case "metricGte": return value >= target;
+		case "metricGt": return value > target;
+		case "metricLte": return value <= target;
+		case "metricLt": return value < target;
+		case "metricBetween": return value >= target && value <= Number(filter.expression2);
+		default: return true;
+	}
+}
+function matchesTopLevelPage(row) {
+	return (normalizeUrl(dimensionValue(row, "page")).match(/\//g)?.length ?? 0) <= 1;
+}
+function assertSchemaInSync(options) {
+	const { label, schema, tableKeyToName, mode } = options;
+	for (const [key, table] of Object.entries(schema)) {
+		const sourceCols = SCHEMAS[tableKeyToName(key)].columns.map((c) => c.name).sort();
+		const drizzleCols = Object.keys(table[Symbol.for("drizzle:Columns")] ?? {}).sort();
+		const missing = sourceCols.filter((c) => !drizzleCols.includes(c));
+		const extra = mode === "exact" ? drizzleCols.filter((c) => !sourceCols.includes(c)) : [];
+		if (missing.length > 0 || extra.length > 0) throw new Error(`${label} drizzle schema for '${key}' drifted from SCHEMAS. Missing: [${missing.join(", ")}]. Extra: [${extra.join(", ")}].`);
+	}
+}
+function isSqlQuerySource(s) {
+	return typeof s.executeSql === "function";
+}
+export { getFilterDimensions as a, matchesMetricFilter as c, createSqlQuerySource as d, getDimensionFilters as i, matchesTopLevelPage as l, assertSchemaInSync as n, getInternalFilters as o, dimensionValue as r, matchesDimensionFilter as s, isSqlQuerySource as t, metricValue as u };

package/dist/_chunks/source-types.d.mts

@@ -0,0 +1,31 @@
+import { PlannerCapabilities } from "gscdump/query/plan";
+import { TableName } from "gscdump/contracts";
+import { BuilderState } from "gscdump/query";
+type QueryRow = Record<string, unknown>;
+interface FileSet {
+  table: TableName;
+  partitions: string[];
+}
+interface ExecuteSqlOptions {
+  fileSets?: Record<string, FileSet>;
+}
+interface SourceCapabilities extends PlannerCapabilities {
+  attachedTables?: boolean;
+  fileSets?: boolean;
+  localSource?: boolean;
+}
+interface RowQuerySource {
+  name?: string;
+  capabilities: SourceCapabilities;
+  queryRows: (state: BuilderState) => Promise<QueryRow[]>;
+  readonly executeSql?: undefined;
+}
+interface SqlQuerySource {
+  name?: string;
+  capabilities: SourceCapabilities;
+  queryRows: (state: BuilderState) => Promise<QueryRow[]>;
+  executeSql: (sql: string, params?: unknown[], opts?: ExecuteSqlOptions) => Promise<QueryRow[]>;
+}
+type AnalysisQuerySource = RowQuerySource | SqlQuerySource;
+declare function isSqlQuerySource(s: AnalysisQuerySource): s is SqlQuerySource;
+export { RowQuerySource as a, isSqlQuerySource as c, QueryRow as i, ExecuteSqlOptions as n, SourceCapabilities as o, FileSet as r, SqlQuerySource as s, AnalysisQuerySource as t };

package/dist/analysis-types.d.mts

@@ -0,0 +1,2 @@
+import { i as num, n as AnalysisResult, r as AnalysisTool, t as AnalysisParams } from "./_chunks/analysis-types.mjs";
+export { AnalysisParams, AnalysisResult, AnalysisTool, num };

package/dist/analysis-types.mjs

@@ -0,0 +1,7 @@
+function num(v) {
+	if (typeof v === "number") return v;
+	if (typeof v === "bigint") return Number(v);
+	if (v == null) return 0;
+	return Number(v);
+}
+export { num };

package/dist/analyzer/index.d.mts

@@ -0,0 +1,59 @@
+import { n as AnalysisResult, t as AnalysisParams } from "../_chunks/analysis-types.mjs";
+import { r as FileSet, t as AnalysisQuerySource } from "../_chunks/source-types.mjs";
+import { a as Analyzer, c as ReduceContext, d as SqlPlan, f as TypedRowQuery, i as createAnalyzerRegistry, l as RowQueriesPlan, n as AnalyzerRegistryInit, o as Capability, r as AnalyzerVariants, s as Plan, t as AnalyzerRegistry, u as SqlExtraQuery } from "../_chunks/registry.mjs";
+import { BuilderState } from "gscdump/query";
+interface SqlPlanSpec {
+  sql: string;
+  params: unknown[];
+  current: FileSet;
+  previous?: FileSet;
+  extraFiles?: Record<string, FileSet>;
+  extraQueries?: SqlExtraQuery[];
+  requiresAttachedTables?: boolean;
+}
+interface ReduceCtx<InputRow> {
+  /** Extra SQL-query results keyed by `SqlExtraQuery.name` (SQL path only). */
+  extras?: Record<string, InputRow[]>;
+}
+type Reducer<Params, InputRow, Result> = (rows: InputRow[] | Record<string, InputRow[]>, params: Params, ctx: ReduceCtx<InputRow>) => {
+  results: Result;
+  meta?: Record<string, unknown>;
+};
+interface DefineAnalyzerOptions<Params extends AnalysisParams, InputRow, Result> {
+  id: string;
+  /**
+   * Shared reducer used by both SQL and row paths. Use this when the
+   * post-aggregation row count is small and filter/sort/derive can live in
+   * one place. Mutually exclusive with `reduceSql` / `reduceRows`.
+   */
+  reduce?: Reducer<Params, InputRow, Result>;
+  /** SQL-only reducer. Required when `buildSql` is set without `reduce`. */
+  reduceSql?: Reducer<Params, InputRow, Result>;
+  /** Row-only reducer. Required when `buildRows` is set without `reduce`. */
+  reduceRows?: Reducer<Params, InputRow, Result>;
+  /** SQL plan builder. Omit if the analyzer has no SQL path. */
+  buildSql?: (params: Params) => SqlPlanSpec;
+  /** Row plan builder. Omit if the analyzer has no row path. */
+  buildRows?: (params: Params) => Record<string, BuilderState>;
+  /** Capabilities required by the SQL plan. Defaults to `['executeSql', 'partitionedParquet']`. */
+  sqlRequires?: readonly Capability[];
+  /** Capabilities required by the row plan. Defaults to `[]`. */
+  rowsRequires?: readonly Capability[];
+}
+interface DefinedAnalyzer {
+  id: string;
+  sql?: Analyzer;
+  rows?: Analyzer;
+}
+declare function defineAnalyzer<Params extends AnalysisParams, InputRow, Result>(opts: DefineAnalyzerOptions<Params, InputRow, Result>): DefinedAnalyzer;
+declare class AnalyzerCapabilityError extends Error {
+  readonly tool: string;
+  readonly missing: readonly Capability[];
+  constructor(tool: string, missing: readonly Capability[]);
+}
+/**
+ * Run an analyzer against a generic `AnalysisQuerySource`. The registry is
+ * an explicit parameter — callers build one via `createAnalyzerRegistry`.
+ */
+declare function runAnalyzerFromSource(source: AnalysisQuerySource, params: AnalysisParams, registry: AnalyzerRegistry): Promise<AnalysisResult>;
+export { type Analyzer, AnalyzerCapabilityError, type AnalyzerRegistry, type AnalyzerRegistryInit, type AnalyzerVariants, type Capability, type DefineAnalyzerOptions, type DefinedAnalyzer, type Plan, type ReduceContext, type ReduceCtx, type Reducer, type RowQueriesPlan, type SqlExtraQuery, type SqlPlan, type SqlPlanSpec, type TypedRowQuery, createAnalyzerRegistry, defineAnalyzer, runAnalyzerFromSource };

package/dist/analyzer/index.mjs

@@ -0,0 +1,104 @@
+import { n as runAnalyzerFromSource, t as AnalyzerCapabilityError } from "../_chunks/dispatch.mjs";
+const DEFAULT_SQL_REQUIRES = ["executeSql", "partitionedParquet"];
+function defineAnalyzer(opts) {
+	const { id, reduce, reduceSql, reduceRows, buildSql, buildRows, sqlRequires = DEFAULT_SQL_REQUIRES, rowsRequires = [] } = opts;
+	const sqlReducer = reduceSql ?? reduce;
+	const rowsReducer = reduceRows ?? reduce;
+	if (buildSql && !sqlReducer) throw new Error(`defineAnalyzer(${id}): buildSql requires reduce or reduceSql`);
+	if (buildRows && !rowsReducer) throw new Error(`defineAnalyzer(${id}): buildRows requires reduce or reduceRows`);
+	const wrap = (fn) => (rows, params, ctx) => {
+		return fn(Array.isArray(rows) ? rows : pickSingle(rows) ?? rows, params, ctx);
+	};
+	return {
+		id,
+		sql: buildSql && sqlReducer ? {
+			id,
+			requires: sqlRequires,
+			build(params) {
+				const spec = buildSql(params);
+				return {
+					kind: "sql",
+					sql: spec.sql,
+					params: spec.params,
+					current: spec.current,
+					previous: spec.previous,
+					extraFiles: spec.extraFiles,
+					extraQueries: spec.extraQueries,
+					requiresAttachedTables: spec.requiresAttachedTables
+				};
+			},
+			reduce(rows, ctx) {
+				const { results, meta } = wrap(sqlReducer)(rows, ctx.params, { extras: ctx.extras });
+				return {
+					results,
+					meta
+				};
+			}
+		} : void 0,
+		rows: buildRows && rowsReducer ? {
+			id,
+			requires: rowsRequires,
+			build(params) {
+				const queries = buildRows(params);
+				return {
+					kind: "rows",
+					queries: Object.fromEntries(Object.entries(queries).map(([k, state]) => [k, { state }]))
+				};
+			},
+			reduce(rows, ctx) {
+				const { results, meta } = wrap(rowsReducer)(rows, ctx.params, {});
+				return {
+					results,
+					meta
+				};
+			}
+		} : void 0
+	};
+}
+function pickSingle(rows) {
+	const keys = Object.keys(rows);
+	return keys.length === 1 ? rows[keys[0]] : void 0;
+}
+function createAnalyzerRegistry(init = {}) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const a of init.rows ?? []) {
+		const entry = byId.get(a.id) ?? {};
+		entry.rows = a;
+		byId.set(a.id, entry);
+	}
+	for (const a of init.sql ?? []) {
+		const entry = byId.get(a.id) ?? {};
+		entry.sql = a;
+		byId.set(a.id, entry);
+	}
+	const listAnalyzerIds = () => [...byId.keys()].sort();
+	const getAnalyzerVariants = (id) => byId.get(id);
+	const resolveAnalyzer = (id, sourceSupportsSql) => {
+		const variants = byId.get(id);
+		if (!variants) return void 0;
+		if (sourceSupportsSql) return variants.sql ?? variants.rows;
+		return variants.rows;
+	};
+	const listAnalyzersFor = (sourceSupportsSql) => {
+		const out = [];
+		for (const id of listAnalyzerIds()) {
+			const a = resolveAnalyzer(id, sourceSupportsSql);
+			if (a) out.push(a);
+		}
+		return out;
+	};
+	const listAnalyzerIdsFor = (source) => {
+		const sourceSupportsSql = typeof source.executeSql === "function";
+		const out = [];
+		for (const id of listAnalyzerIds()) if (resolveAnalyzer(id, sourceSupportsSql)) out.push(id);
+		return out;
+	};
+	return {
+		listAnalyzerIds,
+		getAnalyzerVariants,
+		resolveAnalyzer,
+		listAnalyzersFor,
+		listAnalyzerIdsFor
+	};
+}
+export { AnalyzerCapabilityError, createAnalyzerRegistry, defineAnalyzer, runAnalyzerFromSource };

package/dist/contracts.d.mts

@@ -1,2 +1,2 @@
 import { A as SyncStateFilter, C as QueryResult, D as StorageEngine, E as SearchType, F as Watermark, I as WatermarkFilter, L as WatermarkScope, M as SyncStateScope, N as TableName, O as SyncState, P as TenantCtx, R as WriteCtx, S as QueryExecutor, T as RunSQLOptions, a as DataSource, b as QueryExecuteOptions, c as FileSetRef, d as LockScope, f as ManifestEntry, h as ParquetCodec, j as SyncStateKind, k as SyncStateDetail, l as GcCtx, m as ManifestStore, n as CompactionTier, o as EngineOptions, t as CodecCtx, u as ListLiveFilter, w as Row, x as QueryExecuteResult, y as QueryCtx, z as WriteResult } from "./_chunks/storage.mjs";
-export { type CodecCtx, type CompactionTier, type DataSource, type EngineOptions, type FileSetRef, type GcCtx, type ListLiveFilter, type LockScope, type ManifestEntry, type ManifestStore, type ParquetCodec, type QueryCtx, type QueryExecuteOptions, type QueryExecuteResult, type QueryExecutor, type QueryResult, type Row, type RunSQLOptions, type SearchType, type StorageEngine, type SyncState, type SyncStateDetail, type SyncStateFilter, type SyncStateKind, type SyncStateScope, type TableName, type TenantCtx, type Watermark, type WatermarkFilter, type WatermarkScope, type WriteCtx, type WriteResult };
+export { CodecCtx, CompactionTier, DataSource, EngineOptions, FileSetRef, GcCtx, ListLiveFilter, LockScope, ManifestEntry, ManifestStore, ParquetCodec, QueryCtx, QueryExecuteOptions, QueryExecuteResult, QueryExecutor, QueryResult, Row, RunSQLOptions, SearchType, StorageEngine, SyncState, SyncStateDetail, SyncStateFilter, SyncStateKind, SyncStateScope, TableName, TenantCtx, Watermark, WatermarkFilter, WatermarkScope, WriteCtx, WriteResult };

package/dist/period/index.d.mts

@@ -0,0 +1,57 @@
+import { t as AnalysisParams } from "../_chunks/analysis-types.mjs";
+type WindowPreset = 'last-7d' | 'last-28d' | 'last-30d' | 'last-90d' | 'last-180d' | 'last-365d' | 'mtd' | 'ytd' | 'custom';
+type ComparisonMode = 'none' | 'prev-period' | 'yoy';
+interface ResolveWindowOptions {
+  preset: WindowPreset;
+  comparison?: ComparisonMode;
+  anchor?: string;
+  start?: string;
+  end?: string;
+}
+interface ResolvedWindow {
+  start: string;
+  end: string;
+  days: number;
+  comparison?: {
+    start: string;
+    end: string;
+  };
+}
+interface AnalysisPeriod {
+  startDate: string;
+  endDate: string;
+}
+interface ComparisonPeriod {
+  current: AnalysisPeriod;
+  previous: AnalysisPeriod;
+}
+declare function defaultEndDate(): string;
+declare function defaultStartDate(): string;
+declare function periodOf(params: AnalysisParams): AnalysisPeriod;
+declare function comparisonOf(params: AnalysisParams): ComparisonPeriod;
+declare function resolveWindow(opts: ResolveWindowOptions): ResolvedWindow;
+/** Convert a ResolvedWindow into the AnalysisPeriod / ComparisonPeriod shape. */
+declare function windowToPeriod(w: ResolvedWindow): AnalysisPeriod;
+declare function windowToComparisonPeriod(w: ResolvedWindow): ComparisonPeriod | undefined;
+interface PadTimeseriesOptions<T> {
+  /** ISO date (YYYY-MM-DD), inclusive lower bound. */
+  startDate: string;
+  /** ISO date (YYYY-MM-DD), inclusive upper bound. */
+  endDate: string;
+  /**
+   * Row to insert for missing dates. Defaults to `{ clicks: 0, impressions: 0, ctr: 0, position: 0 }`.
+   * The `date` field is set automatically.
+   */
+  fill?: Omit<T, 'date'>;
+  /** Row-field that carries the ISO date. Defaults to `date`. */
+  dateKey?: string;
+}
+type DateRowShape = Record<string, unknown> & {
+  date?: unknown;
+};
+/**
+ * Pad rows so every calendar day in `[startDate, endDate]` appears at least
+ * once. Existing dates keep all their rows (grouped timeseries safe).
+ */
+declare function padTimeseries<T extends DateRowShape = DateRowShape>(rows: readonly T[], options: PadTimeseriesOptions<T>): T[];
+export { AnalysisPeriod, ComparisonMode, ComparisonPeriod, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, defaultEndDate, defaultStartDate, padTimeseries, periodOf, resolveWindow, windowToComparisonPeriod, windowToPeriod };