@gscdump/analysis 0.4.0

package/dist/source/index.mjs

@@ -0,0 +1,1865 @@
+import { createEngine as createBrowserQuerySource } from "@gscdump/engine-wasm";
+import { assertDimensionsSupported, getDimensionFilters, getFilterDimensions, isSqlQuerySource, matchesDimensionFilter, matchesMetricFilter, matchesTopLevelPage, metricValue } from "@gscdump/engine/resolver";
+import { buildLogicalPlan } from "gscdump/query/plan";
+import { between, clicks, date, extractMetricFilters, extractSpecialOperatorFilters, gsc, page, query } from "gscdump/query";
+import { enumeratePartitions } from "@gscdump/engine/planner";
+import { METRIC_EXPR } from "@gscdump/engine/sql-fragments";
+import { daysAgo } from "gscdump";
+import { createEngine as createSqliteQuerySource } from "@gscdump/engine-sqlite";
+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" } : {};
+	return {
+		results,
+		meta: {
+			tool: params.type,
+			...sourceMeta,
+			...meta
+		}
+	};
+}
+async function analyzeFromSource(source, params, registry) {
+	return runAnalyzerFromSource(source, params, registry);
+}
+function isMetricDimension$2(dim) {
+	return [
+		"clicks",
+		"impressions",
+		"ctr",
+		"position"
+	].includes(dim);
+}
+const ENGINE_QUERY_CAPABILITIES = {
+	regex: true,
+	multiDataset: false,
+	comparisonJoin: false,
+	windowTotals: false
+};
+const ENGINE_SOURCE_CAPABILITIES = {
+	...ENGINE_QUERY_CAPABILITIES,
+	fileSets: true,
+	localSource: true
+};
+function createEngineQuerySource(options) {
+	const { engine, ctx } = options;
+	return {
+		name: "engine",
+		capabilities: ENGINE_SOURCE_CAPABILITIES,
+		async queryRows(state) {
+			const filterDims = getFilterDimensions(state.filter, isMetricDimension$2);
+			assertDimensionsSupported([...state.dimensions, ...filterDims], "stored", "engine query source");
+			if (state.dimensions.includes("queryCanonical") || filterDims.includes("queryCanonical")) throw new Error("engine query source does not support queryCanonical; use browser/sqlite query sources for derived dimensions");
+			return (await engine.query(ctx, state)).rows;
+		},
+		async executeSql(sql, params, opts) {
+			const fileSets = opts?.fileSets;
+			if (!fileSets?.FILES) throw new Error("engine query source: executeSql requires opts.fileSets with a FILES entry");
+			const { rows } = await engine.runSQL({
+				ctx,
+				table: fileSets.FILES.table,
+				fileSets,
+				sql,
+				params: params ?? []
+			});
+			return rows;
+		}
+	};
+}
+async function runAnalyzerWithEngine(deps, ctx, params, registry) {
+	return runAnalyzerFromSource(createEngineQuerySource({
+		engine: deps.engine,
+		ctx
+	}), params, registry);
+}
+async function collectRows(gen) {
+	const out = [];
+	for await (const batch of gen) out.push(...batch);
+	return out;
+}
+async function fetchGscTopN(opts) {
+	const { client, siteUrl, dimension, range, orderByClicksDesc, limit, sliceTop } = opts;
+	let builder = gsc.select(dimension).where(between(date, range.start, range.end));
+	if (orderByClicksDesc) builder = builder.orderBy(clicks, "desc");
+	if (typeof limit === "number") builder = builder.limit(limit);
+	const mapped = (await collectRows(client.query(siteUrl, builder))).map((r) => {
+		const row = r;
+		const key = row[dimension.dimension];
+		if (typeof key !== "string" || !key) return null;
+		const impressions = Number(row.impressions ?? 0);
+		const position = Number(row.position ?? 0);
+		return {
+			key,
+			clicks: Number(row.clicks ?? 0),
+			impressions,
+			sum_position: position * impressions
+		};
+	}).filter((x) => x != null);
+	if (!orderByClicksDesc) mapped.sort((a, b) => b.clicks - a.clicks);
+	return typeof sliceTop === "number" ? mapped.slice(0, sliceTop) : mapped;
+}
+async function fetchGscDaily(opts) {
+	const { client, siteUrl, range } = opts;
+	const builder = gsc.select(date).where(between(date, range.start, range.end));
+	return (await collectRows(client.query(siteUrl, builder))).map((r) => {
+		const row = r;
+		if (!row.date) return null;
+		const impressions = row.impressions ?? 0;
+		return {
+			date: Date.parse(`${row.date}T00:00:00Z`),
+			clicks: row.clicks ?? 0,
+			impressions,
+			sum_position: (row.position ?? 0) * impressions,
+			anonymizedImpressionsPct: 0
+		};
+	}).filter((x) => x != null).sort((a, b) => a.date - b.date);
+}
+const METRIC_NAMES = [
+	"clicks",
+	"impressions",
+	"ctr",
+	"position"
+];
+function isMetricDimension$1(dim) {
+	return METRIC_NAMES.includes(dim);
+}
+function applyBuilderStatePostProcessing(rows, state) {
+	const dimensionFilters = getDimensionFilters(state.filter, isMetricDimension$1);
+	const metricFilters = extractMetricFilters(state.filter);
+	const specialFilters = extractSpecialOperatorFilters(state.filter);
+	const ordered = [...rows.filter((row) => {
+		if (!dimensionFilters.every((filter) => matchesDimensionFilter(row, filter))) return false;
+		if (!metricFilters.every((filter) => matchesMetricFilter(row, filter))) return false;
+		if (specialFilters.some((filter) => filter.operator === "topLevel") && !matchesTopLevelPage(row)) return false;
+		return true;
+	})].sort((a, b) => {
+		const column = state.orderBy?.column ?? "clicks";
+		const dir = state.orderBy?.dir ?? "desc";
+		const left = column === "date" ? String(a.date ?? "") : metricValue(a, column);
+		const right = column === "date" ? String(b.date ?? "") : metricValue(b, column);
+		if (left === right) return 0;
+		if (dir === "asc") return left < right ? -1 : 1;
+		return left > right ? -1 : 1;
+	});
+	const offset = Math.max(0, Number(state.startRow ?? 0));
+	const limit = Math.max(0, Number((state.rowLimit ?? ordered.length) || 0));
+	return ordered.slice(offset, offset + limit);
+}
+const GSC_API_CAPABILITIES = {
+	regex: true,
+	multiDataset: false,
+	comparisonJoin: false,
+	windowTotals: false
+};
+function isMetricDimension(dim) {
+	return [
+		"clicks",
+		"impressions",
+		"ctr",
+		"position"
+	].includes(dim);
+}
+function builderFromState(state) {
+	return { getState: () => state };
+}
+function createGscApiQuerySource(options) {
+	const { client, siteUrl } = options;
+	return {
+		name: "gsc-api",
+		capabilities: GSC_API_CAPABILITIES,
+		async queryRows(state) {
+			buildLogicalPlan(state, GSC_API_CAPABILITIES);
+			const filterDims = getFilterDimensions(state.filter, isMetricDimension);
+			assertDimensionsSupported([...state.dimensions, ...filterDims], "api", "gsc-api query source");
+			return applyBuilderStatePostProcessing(await collectRows(client.query(siteUrl, builderFromState(state))), state);
+		}
+	};
+}
+const IN_MEMORY_DEFAULT_CAPABILITIES = {
+	regex: true,
+	multiDataset: true,
+	comparisonJoin: true,
+	windowTotals: true
+};
+function createInMemoryQuerySource(options) {
+	return {
+		name: "memory",
+		capabilities: options.capabilities ?? IN_MEMORY_DEFAULT_CAPABILITIES,
+		async queryRows(state) {
+			return await options.queryRows(state);
+		}
+	};
+}
+const DEFAULT_LIMIT$1 = 25e3;
+function keywordsQueryState(period, limit = DEFAULT_LIMIT$1) {
+	return gsc.select(query, page).where(between(date, period.startDate, period.endDate)).limit(limit).getState();
+}
+function pagesQueryState(period, limit = DEFAULT_LIMIT$1) {
+	return gsc.select(page).where(between(date, period.startDate, period.endDate)).limit(limit).getState();
+}
+function datesQueryState(period, limit = DEFAULT_LIMIT$1) {
+	return gsc.select(date).where(between(date, period.startDate, period.endDate)).limit(limit).getState();
+}
+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 defaultEndDate() {
+	return daysAgo(3);
+}
+function defaultStartDate() {
+	return daysAgo(31);
+}
+function periodOf(params) {
+	return {
+		startDate: params.startDate || defaultStartDate(),
+		endDate: params.endDate || defaultEndDate()
+	};
+}
+function comparisonOf(params) {
+	if (!params.prevStartDate || !params.prevEndDate) throw new Error(`${params.type} analysis requires prevStartDate and prevEndDate`);
+	return {
+		current: periodOf(params),
+		previous: {
+			startDate: params.prevStartDate,
+			endDate: params.prevEndDate
+		}
+	};
+}
+function num(v) {
+	if (typeof v === "number") return v;
+	if (typeof v === "bigint") return Number(v);
+	if (v == null) return 0;
+	return Number(v);
+}
+function buildPeriodMap(rows, key, value, filter) {
+	const out = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		if (filter && !filter(row)) continue;
+		out.set(key(row), value(row));
+	}
+	return out;
+}
+function createSorter(getValue, defaultMetric, defaultOrder = "desc") {
+	return (items, sortBy = defaultMetric, sortOrder = defaultOrder) => {
+		const mult = sortOrder === "desc" ? -1 : 1;
+		return [...items].sort((a, b) => (getValue(a, sortBy) - getValue(b, sortBy)) * mult);
+	};
+}
+function createMetricSorter(defaultMetric, orderByMetric) {
+	return (items, sortBy = defaultMetric) => {
+		const mult = orderByMetric[sortBy] === "desc" ? -1 : 1;
+		return [...items].sort((a, b) => (a[sortBy] - b[sortBy]) * mult);
+	};
+}
+function escapeRegexAlt(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function str$5(v) {
+	return v == null ? "" : String(v);
+}
+function analyzeBrandSegmentation(keywords, options) {
+	const { brandTerms, minImpressions = 10 } = options;
+	const lowerBrandTerms = brandTerms.map((t) => t.toLowerCase());
+	const brand = [];
+	const nonBrand = [];
+	for (const row of keywords) {
+		if (num(row.impressions) < minImpressions) continue;
+		if (lowerBrandTerms.some((term) => row.query.toLowerCase().includes(term))) brand.push(row);
+		else nonBrand.push(row);
+	}
+	const brandClicks = brand.reduce((sum, k) => sum + num(k.clicks), 0);
+	const nonBrandClicks = nonBrand.reduce((sum, k) => sum + num(k.clicks), 0);
+	const totalClicks = brandClicks + nonBrandClicks;
+	return {
+		brand,
+		nonBrand,
+		summary: {
+			brandClicks,
+			nonBrandClicks,
+			brandShare: totalClicks > 0 ? brandClicks / totalClicks : 0,
+			brandImpressions: brand.reduce((sum, k) => sum + num(k.impressions), 0),
+			nonBrandImpressions: nonBrand.reduce((sum, k) => sum + num(k.impressions), 0)
+		}
+	};
+}
+defineAnalyzer({
+	id: "brand",
+	buildSql(params) {
+		if (!params.brandTerms?.length) throw new Error("Brand analysis requires brandTerms");
+		const { startDate, endDate } = periodOf(params);
+		const minImpressions = params.minImpressions ?? 10;
+		const limit = params.limit ?? 1e4;
+		const regex = `(${params.brandTerms.map((t) => escapeRegexAlt(t.toLowerCase())).join("|")})`;
+		return {
+			sql: `
+    WITH agg AS (
+      SELECT
+        query,
+        url AS page,
+        ${METRIC_EXPR.clicks} AS clicks,
+        ${METRIC_EXPR.impressions} AS impressions,
+        ${METRIC_EXPR.ctr} AS ctr,
+        ${METRIC_EXPR.position} AS position
+      FROM read_parquet({{FILES}}, union_by_name = true)
+      WHERE date >= ? AND date <= ?
+      GROUP BY query, url
+      HAVING SUM(impressions) >= ?
+    )
+    SELECT
+      query, page, clicks, impressions, ctr, position,
+      CASE WHEN regexp_matches(LOWER(query), ?) THEN 'brand' ELSE 'non-brand' END AS segment
+    FROM agg
+    ORDER BY clicks DESC
+    LIMIT ${Number(limit)}
+  `,
+			params: [
+				startDate,
+				endDate,
+				minImpressions,
+				regex
+			],
+			current: {
+				table: "page_keywords",
+				partitions: enumeratePartitions(startDate, endDate)
+			}
+		};
+	},
+	reduceSql(rows) {
+		const normalized = (Array.isArray(rows) ? rows : []).map((r) => ({
+			query: str$5(r.query),
+			page: r.page == null ? void 0 : str$5(r.page),
+			clicks: num(r.clicks),
+			impressions: num(r.impressions),
+			ctr: num(r.ctr),
+			position: num(r.position),
+			segment: str$5(r.segment)
+		}));
+		let brandClicks = 0;
+		let nonBrandClicks = 0;
+		let brandImpressions = 0;
+		let nonBrandImpressions = 0;
+		for (const r of normalized) if (r.segment === "brand") {
+			brandClicks += r.clicks;
+			brandImpressions += r.impressions;
+		} else {
+			nonBrandClicks += r.clicks;
+			nonBrandImpressions += r.impressions;
+		}
+		const totalClicks = brandClicks + nonBrandClicks;
+		return {
+			results: normalized,
+			meta: {
+				total: normalized.length,
+				summary: {
+					brandClicks,
+					nonBrandClicks,
+					brandShare: totalClicks > 0 ? brandClicks / totalClicks : 0,
+					brandImpressions,
+					nonBrandImpressions
+				}
+			}
+		};
+	},
+	buildRows(params) {
+		return { keywords: keywordsQueryState(periodOf(params), params.limit) };
+	},
+	reduceRows(rows, params) {
+		if (!params.brandTerms?.length) throw new Error("Brand analysis requires brandTerms");
+		const result = analyzeBrandSegmentation(Array.isArray(rows) ? rows : [], {
+			brandTerms: params.brandTerms,
+			minImpressions: params.minImpressions
+		});
+		return {
+			results: [...result.brand.map((r) => ({
+				...r,
+				segment: "brand"
+			})), ...result.nonBrand.map((r) => ({
+				...r,
+				segment: "non-brand"
+			}))],
+			meta: { summary: result.summary }
+		};
+	}
+});
+const INTENT_PREFIXES_REGEX = "^(how to|what is|what are|why is|why do|where to|when to|best|top|vs|versus|compare|review|buy|cheap|free|near me)(\\s|$)";
+const INTENT_PREFIXES = [
+	"how to",
+	"what is",
+	"what are",
+	"why is",
+	"why do",
+	"where to",
+	"when to",
+	"best",
+	"top",
+	"vs",
+	"versus",
+	"compare",
+	"review",
+	"buy",
+	"cheap",
+	"free",
+	"near me"
+];
+const WHITESPACE_RE = /\s+/;
+function str$4(v) {
+	return v == null ? "" : String(v);
+}
+function parseJsonList$3(v) {
+	if (Array.isArray(v)) return v;
+	if (typeof v === "string" && v.length > 0) {
+		const parsed = JSON.parse(v);
+		return Array.isArray(parsed) ? parsed : [];
+	}
+	return [];
+}
+function extractIntentPrefix(keyword) {
+	const lower = keyword.toLowerCase();
+	for (const prefix of INTENT_PREFIXES) if (lower.startsWith(`${prefix} `) || lower.startsWith(prefix)) return prefix;
+	return null;
+}
+function extractWordPrefix(keyword, wordCount = 2) {
+	const words = keyword.toLowerCase().split(WHITESPACE_RE).filter(Boolean);
+	if (words.length < wordCount + 1) return null;
+	return words.slice(0, wordCount).join(" ");
+}
+function analyzeClustering(keywords, options = {}) {
+	const { minClusterSize = 2, minImpressions = 10, clusterBy = "both" } = options;
+	const filtered = keywords.filter((k) => num(k.impressions) >= minImpressions);
+	const clusterMap = /* @__PURE__ */ new Map();
+	const clusteredKeywords = /* @__PURE__ */ new Set();
+	if (clusterBy === "intent" || clusterBy === "both") for (const kw of filtered) {
+		const intent = extractIntentPrefix(kw.query);
+		if (intent) {
+			const existing = clusterMap.get(intent);
+			if (existing) existing.keywords.push(kw);
+			else clusterMap.set(intent, {
+				type: "intent",
+				keywords: [kw]
+			});
+			clusteredKeywords.add(kw.query);
+		}
+	}
+	if (clusterBy === "prefix" || clusterBy === "both") {
+		const unclustered = filtered.filter((kw) => !clusteredKeywords.has(kw.query));
+		const prefixMap = /* @__PURE__ */ new Map();
+		for (const kw of unclustered) {
+			const prefix = extractWordPrefix(kw.query);
+			if (prefix) {
+				const existing = prefixMap.get(prefix);
+				if (existing) existing.push(kw);
+				else prefixMap.set(prefix, [kw]);
+			}
+		}
+		for (const [prefix, kws] of prefixMap) if (kws.length >= minClusterSize) {
+			clusterMap.set(prefix, {
+				type: "prefix",
+				keywords: kws
+			});
+			kws.forEach((kw) => clusteredKeywords.add(kw.query));
+		}
+	}
+	const clusters = [];
+	for (const [name, data] of clusterMap) {
+		if (data.keywords.length < minClusterSize) continue;
+		const totalClicks = data.keywords.reduce((sum, k) => sum + num(k.clicks), 0);
+		const totalImpressions = data.keywords.reduce((sum, k) => sum + num(k.impressions), 0);
+		const avgPosition = data.keywords.reduce((sum, k) => sum + num(k.position), 0) / data.keywords.length;
+		clusters.push({
+			clusterName: name,
+			clusterType: data.type,
+			keywords: data.keywords,
+			totalClicks,
+			totalImpressions,
+			avgPosition,
+			keywordCount: data.keywords.length
+		});
+	}
+	clusters.sort((a, b) => b.totalClicks - a.totalClicks);
+	return {
+		clusters,
+		unclustered: filtered.filter((kw) => !clusteredKeywords.has(kw.query))
+	};
+}
+defineAnalyzer({
+	id: "clustering",
+	buildSql(params) {
+		const { startDate, endDate } = periodOf(params);
+		const minImpressions = params.minImpressions ?? 10;
+		const minClusterSize = params.minClusterSize ?? 2;
+		const clusterBy = params.clusterBy ?? "both";
+		const doIntent = clusterBy === "intent" || clusterBy === "both";
+		const doPrefix = clusterBy === "prefix" || clusterBy === "both";
+		const intentExpr = doIntent ? `NULLIF(regexp_extract(LOWER(query), '${INTENT_PREFIXES_REGEX}', 1), '')` : `CAST(NULL AS VARCHAR)`;
+		const prefixExpr = doPrefix ? `CASE WHEN len(regexp_split_to_array(LOWER(query), '\\s+')) >= 3
+          THEN array_to_string(list_slice(regexp_split_to_array(LOWER(query), '\\s+'), 1, 2), ' ')
+          ELSE CAST(NULL AS VARCHAR) END` : `CAST(NULL AS VARCHAR)`;
+		return {
+			sql: `
+      WITH agg AS (
+        SELECT
+          query,
+          ${METRIC_EXPR.clicks} AS clicks,
+          ${METRIC_EXPR.impressions} AS impressions,
+          ${METRIC_EXPR.ctr} AS ctr,
+          ${METRIC_EXPR.position} AS position
+        FROM read_parquet({{FILES}}, union_by_name = true)
+        WHERE date >= ? AND date <= ?
+        GROUP BY query
+        HAVING SUM(impressions) >= ?
+      ),
+      classified AS (
+        SELECT
+          query, clicks, impressions, ctr, position,
+          ${intentExpr} AS intent_prefix,
+          ${prefixExpr} AS word_prefix
+        FROM agg
+      ),
+      keyed AS (
+        SELECT
+          query, clicks, impressions, ctr, position,
+          COALESCE(intent_prefix, word_prefix) AS cluster_name,
+          CASE WHEN intent_prefix IS NOT NULL THEN 'intent' ELSE 'prefix' END AS cluster_type
+        FROM classified
+        WHERE COALESCE(intent_prefix, word_prefix) IS NOT NULL
+      )
+      SELECT
+        cluster_name AS clusterName,
+        any_value(cluster_type) AS clusterType,
+        CAST(COUNT(*) AS DOUBLE) AS keywordCount,
+        ${METRIC_EXPR.clicks} AS totalClicks,
+        ${METRIC_EXPR.impressions} AS totalImpressions,
+        AVG(position) AS avgPosition,
+        to_json(list({ 'query': query, 'clicks': clicks, 'impressions': impressions, 'ctr': ctr, 'position': position })) AS keywords
+      FROM keyed
+      GROUP BY cluster_name
+      HAVING COUNT(*) >= ?
+      ORDER BY totalClicks DESC
+    `,
+			params: [
+				startDate,
+				endDate,
+				minImpressions,
+				minClusterSize
+			],
+			current: {
+				table: "keywords",
+				partitions: enumeratePartitions(startDate, endDate)
+			}
+		};
+	},
+	reduceSql(rows) {
+		const clusters = (Array.isArray(rows) ? rows : []).map((r) => ({
+			clusterName: str$4(r.clusterName),
+			clusterType: str$4(r.clusterType),
+			keywordCount: num(r.keywordCount),
+			totalClicks: num(r.totalClicks),
+			totalImpressions: num(r.totalImpressions),
+			avgPosition: num(r.avgPosition),
+			keywords: parseJsonList$3(r.keywords).map((k) => ({
+				query: str$4(k.query),
+				clicks: num(k.clicks),
+				impressions: num(k.impressions),
+				ctr: num(k.ctr),
+				position: num(k.position)
+			}))
+		}));
+		return {
+			results: clusters,
+			meta: {
+				total: clusters.length,
+				totalClusters: clusters.length
+			}
+		};
+	},
+	buildRows(params) {
+		return { keywords: keywordsQueryState(periodOf(params), params.limit) };
+	},
+	reduceRows(rows, params) {
+		const result = analyzeClustering(Array.isArray(rows) ? rows : [], {
+			clusterBy: params.clusterBy,
+			minClusterSize: params.minClusterSize,
+			minImpressions: params.minImpressions
+		});
+		return {
+			results: result.clusters,
+			meta: { totalClusters: result.clusters.length }
+		};
+	}
+});
+function str$3(v) {
+	return v == null ? "" : String(v);
+}
+function parseJsonList$2(v) {
+	if (Array.isArray(v)) return v;
+	if (typeof v === "string" && v.length > 0) {
+		const parsed = JSON.parse(v);
+		return Array.isArray(parsed) ? parsed : [];
+	}
+	return [];
+}
+function calculateGini(values) {
+	if (values.length === 0) return 0;
+	const sorted = [...values].sort((a, b) => a - b);
+	const n = sorted.length;
+	const sum = sorted.reduce((a, b) => a + b, 0);
+	if (sum === 0) return 0;
+	let weightedSum = 0;
+	for (let i = 0; i < n; i++) weightedSum += (2 * (i + 1) - n - 1) * sorted[i];
+	return weightedSum / (n * sum);
+}
+function calculateHHI(shares) {
+	return shares.reduce((sum, share) => sum + (share * 100) ** 2, 0);
+}
+function analyzeConcentration(items, options = {}) {
+	const { topN = 10 } = options;
+	if (items.length === 0) return {
+		giniCoefficient: 0,
+		hhi: 0,
+		topNConcentration: 0,
+		topNItems: [],
+		totalItems: 0,
+		totalClicks: 0,
+		riskLevel: "low"
+	};
+	const sorted = [...items].sort((a, b) => b.clicks - a.clicks);
+	const totalClicks = sorted.reduce((sum, item) => sum + item.clicks, 0);
+	const clickValues = sorted.map((i) => i.clicks);
+	const shares = totalClicks > 0 ? sorted.map((i) => i.clicks / totalClicks) : [];
+	const giniCoefficient = calculateGini(clickValues);
+	const hhi = calculateHHI(shares);
+	const topNItems = sorted.slice(0, topN).map((item) => ({
+		key: item.key,
+		clicks: item.clicks,
+		share: totalClicks > 0 ? item.clicks / totalClicks : 0
+	}));
+	const topNClicks = topNItems.reduce((sum, item) => sum + item.clicks, 0);
+	const topNConcentration = totalClicks > 0 ? topNClicks / totalClicks : 0;
+	let riskLevel = "low";
+	if (hhi > 2500) riskLevel = "high";
+	else if (hhi > 1500) riskLevel = "medium";
+	return {
+		giniCoefficient,
+		hhi,
+		topNConcentration,
+		topNItems,
+		totalItems: items.length,
+		totalClicks,
+		riskLevel
+	};
+}
+function analyzePageConcentration(pages, options) {
+	return analyzeConcentration(pages.map((p) => ({
+		key: p.page,
+		clicks: num(p.clicks)
+	})), options);
+}
+function analyzeKeywordConcentration(keywords, options) {
+	return analyzeConcentration(keywords.map((k) => ({
+		key: k.query,
+		clicks: num(k.clicks)
+	})), options);
+}
+defineAnalyzer({
+	id: "concentration",
+	buildSql(params) {
+		const { startDate, endDate } = periodOf(params);
+		const dim = params.dimension || "pages";
+		const topN = params.topN ?? 10;
+		const table = dim === "keywords" ? "keywords" : "pages";
+		const keyCol = dim === "keywords" ? "query" : "url";
+		return {
+			sql: `
+    WITH items AS (
+      SELECT
+        ${keyCol} AS key,
+        ${METRIC_EXPR.clicks} AS clicks
+      FROM read_parquet({{FILES}}, union_by_name = true)
+      WHERE date >= ? AND date <= ?
+      GROUP BY ${keyCol}
+      HAVING SUM(clicks) > 0
+    ),
+    totals AS (
+      SELECT SUM(clicks) AS total_clicks, COUNT(*) AS total_items FROM items
+    ),
+    ranked AS (
+      SELECT
+        i.key, i.clicks,
+        i.clicks / NULLIF(t.total_clicks, 0) AS share,
+        ROW_NUMBER() OVER (ORDER BY i.clicks DESC, i.key ASC) AS rnk_desc,
+        ROW_NUMBER() OVER (ORDER BY i.clicks ASC, i.key ASC) AS rnk_asc,
+        t.total_clicks AS tclicks,
+        t.total_items AS titems
+      FROM items i, totals t
+    ),
+    gini_num AS (
+      SELECT SUM((2.0 * rnk_asc - titems - 1) * clicks) AS weighted_sum FROM ranked
+    ),
+    hhi_calc AS (
+      SELECT SUM(POWER(share * 100, 2)) AS hhi FROM ranked
+    ),
+    top_list AS (
+      SELECT
+        list({ 'key': key, 'clicks': clicks, 'share': share } ORDER BY clicks DESC, key ASC) AS items,
+        SUM(clicks) AS top_clicks
+      FROM ranked WHERE rnk_desc <= ?
+    )
+    SELECT
+      COALESCE(
+        (SELECT weighted_sum FROM gini_num)
+          / NULLIF((SELECT total_items FROM totals) * (SELECT total_clicks FROM totals), 0),
+        0.0
+      ) AS giniCoefficient,
+      COALESCE((SELECT hhi FROM hhi_calc), 0.0) AS hhi,
+      COALESCE(
+        CAST((SELECT top_clicks FROM top_list) AS DOUBLE)
+          / NULLIF((SELECT total_clicks FROM totals), 0),
+        0.0
+      ) AS topNConcentration,
+      COALESCE((SELECT to_json(items) FROM top_list), '[]') AS topNItems,
+      COALESCE((SELECT total_items FROM totals), 0) AS totalItems,
+      COALESCE((SELECT total_clicks FROM totals), 0.0) AS totalClicks,
+      CASE
+        WHEN COALESCE((SELECT hhi FROM hhi_calc), 0.0) > 2500 THEN 'high'
+        WHEN COALESCE((SELECT hhi FROM hhi_calc), 0.0) > 1500 THEN 'medium'
+        ELSE 'low'
+      END AS riskLevel
+  `,
+			params: [
+				startDate,
+				endDate,
+				topN
+			],
+			current: {
+				table,
+				partitions: enumeratePartitions(startDate, endDate)
+			}
+		};
+	},
+	reduceSql(rows, params) {
+		const r = (Array.isArray(rows) ? rows : [])[0] ?? {};
+		const topRaw = parseJsonList$2(r.topNItems);
+		return {
+			results: [{
+				giniCoefficient: num(r.giniCoefficient),
+				hhi: num(r.hhi),
+				topNConcentration: num(r.topNConcentration),
+				topNItems: topRaw.map((t) => ({
+					key: str$3(t.key),
+					clicks: num(t.clicks),
+					share: num(t.share)
+				})),
+				totalItems: num(r.totalItems),
+				totalClicks: num(r.totalClicks),
+				riskLevel: str$3(r.riskLevel)
+			}],
+			meta: {
+				total: 1,
+				dimension: params.dimension || "pages"
+			}
+		};
+	},
+	buildRows(params) {
+		const dim = params.dimension || "pages";
+		const period = periodOf(params);
+		const out = {};
+		if (dim === "pages") out.pages = pagesQueryState(period, params.limit);
+		else out.keywords = keywordsQueryState(period, params.limit);
+		return out;
+	},
+	reduceRows(rows, params) {
+		const dim = params.dimension || "pages";
+		const arr = Array.isArray(rows) ? rows : rows[dim] ?? [];
+		return {
+			results: [dim === "pages" ? analyzePageConcentration(arr, { topN: params.topN }) : analyzeKeywordConcentration(arr, { topN: params.topN })],
+			meta: { dimension: dim }
+		};
+	}
+});
+const sortResults$2 = createMetricSorter("lostClicks", {
+	lostClicks: "desc",
+	declinePercent: "desc",
+	currentClicks: "asc"
+});
+function str$2(v) {
+	return v == null ? "" : String(v);
+}
+function parseJsonList$1(v) {
+	if (Array.isArray(v)) return v;
+	if (typeof v === "string" && v.length > 0) {
+		const parsed = JSON.parse(v);
+		return Array.isArray(parsed) ? parsed : [];
+	}
+	return [];
+}
+function analyzeDecay(input, options = {}) {
+	const { minPreviousClicks = 50, threshold = .2, sortBy = "lostClicks" } = options;
+	const currentMap = buildPeriodMap(input.current, (r) => r.page, (r) => ({
+		clicks: num(r.clicks),
+		position: num(r.position)
+	}));
+	const previousMap = buildPeriodMap(input.previous, (r) => r.page, (r) => ({
+		clicks: num(r.clicks),
+		position: num(r.position)
+	}), (r) => num(r.clicks) >= minPreviousClicks);
+	const results = [];
+	for (const [page, prev] of previousMap) {
+		const curr = currentMap.get(page) || {
+			clicks: 0,
+			position: 0
+		};
+		const lostClicks = prev.clicks - curr.clicks;
+		const declinePercent = prev.clicks > 0 ? lostClicks / prev.clicks : 0;
+		if (declinePercent >= threshold && lostClicks > 0) results.push({
+			page,
+			currentClicks: curr.clicks,
+			previousClicks: prev.clicks,
+			lostClicks,
+			declinePercent,
+			currentPosition: curr.position,
+			previousPosition: prev.position,
+			positionDrop: curr.position - prev.position
+		});
+	}
+	return sortResults$2(results, sortBy);
+}
+defineAnalyzer({
+	id: "decay",
+	buildSql(params) {
+		const { current: cur, previous: prev } = comparisonOf(params);
+		const minPreviousClicks = params.minPreviousClicks ?? 50;
+		const threshold = params.threshold ?? .2;
+		const limit = params.limit ?? 2e3;
+		return {
+			sql: `
+      WITH cur AS (
+        SELECT
+          url,
+          ${METRIC_EXPR.clicks} AS clicks,
+          ${METRIC_EXPR.position} AS position
+        FROM read_parquet({{FILES}}, union_by_name = true)
+        WHERE date >= ? AND date <= ?
+        GROUP BY url
+      ),
+      prev AS (
+        SELECT
+          url,
+          ${METRIC_EXPR.clicks} AS clicks,
+          ${METRIC_EXPR.position} AS position
+        FROM read_parquet({{FILES_PREV}}, union_by_name = true)
+        WHERE date >= ? AND date <= ?
+        GROUP BY url
+        HAVING SUM(clicks) >= ?
+      ),
+      weekly AS (
+        SELECT url, date_trunc('week', CAST(date AS DATE)) AS week,
+          ${METRIC_EXPR.clicks} AS clicks,
+          ${METRIC_EXPR.impressions} AS impressions
+        FROM (
+          SELECT url, date, clicks, impressions
+          FROM read_parquet({{FILES}}, union_by_name = true)
+          WHERE date >= ? AND date <= ?
+          UNION ALL
+          SELECT url, date, clicks, impressions
+          FROM read_parquet({{FILES_PREV}}, union_by_name = true)
+          WHERE date >= ? AND date <= ?
+        )
+        GROUP BY url, week
+      ),
+      series_by_url AS (
+        SELECT url, to_json(list({
+          'week': strftime(week, '%Y-%m-%d'),
+          'clicks': clicks,
+          'impressions': impressions
+        } ORDER BY week)) AS seriesJson
+        FROM weekly GROUP BY url
+      ),
+      joined AS (
+        SELECT
+          p.url AS page,
+          COALESCE(c.clicks, 0.0) AS currentClicks,
+          p.clicks AS previousClicks,
+          (p.clicks - COALESCE(c.clicks, 0.0)) AS lostClicks,
+          (p.clicks - COALESCE(c.clicks, 0.0)) / NULLIF(p.clicks, 0) AS declinePercent,
+          COALESCE(c.position, 0.0) AS currentPosition,
+          p.position AS previousPosition,
+          (COALESCE(c.position, 0.0) - p.position) AS positionDrop,
+          s.seriesJson
+        FROM prev p
+        LEFT JOIN cur c ON p.url = c.url
+        LEFT JOIN series_by_url s ON p.url = s.url
+      )
+      SELECT *
+      FROM joined
+      WHERE declinePercent >= ? AND lostClicks > 0
+      ORDER BY lostClicks DESC
+      LIMIT ${Number(limit)}
+    `,
+			params: [
+				cur.startDate,
+				cur.endDate,
+				prev.startDate,
+				prev.endDate,
+				minPreviousClicks,
+				cur.startDate,
+				cur.endDate,
+				prev.startDate,
+				prev.endDate,
+				threshold
+			],
+			current: {
+				table: "pages",
+				partitions: enumeratePartitions(cur.startDate, cur.endDate)
+			},
+			previous: {
+				table: "pages",
+				partitions: enumeratePartitions(prev.startDate, prev.endDate)
+			}
+		};
+	},
+	reduceSql(rows) {
+		const arr = Array.isArray(rows) ? rows : [];
+		return {
+			results: arr.map((r) => ({
+				page: str$2(r.page),
+				currentClicks: num(r.currentClicks),
+				previousClicks: num(r.previousClicks),
+				lostClicks: num(r.lostClicks),
+				declinePercent: num(r.declinePercent),
+				currentPosition: num(r.currentPosition),
+				previousPosition: num(r.previousPosition),
+				positionDrop: num(r.positionDrop),
+				series: parseJsonList$1(r.seriesJson).map((s) => ({
+					week: str$2(s.week),
+					clicks: num(s.clicks),
+					impressions: num(s.impressions)
+				}))
+			})),
+			meta: { total: arr.length }
+		};
+	},
+	buildRows(params) {
+		const { current, previous } = comparisonOf(params);
+		return {
+			current: pagesQueryState(current, params.limit),
+			previous: pagesQueryState(previous, params.limit)
+		};
+	},
+	reduceRows(rows, params) {
+		const map = rows && !Array.isArray(rows) ? rows : {
+			current: [],
+			previous: []
+		};
+		const results = analyzeDecay({
+			current: map.current ?? [],
+			previous: map.previous ?? []
+		}, {
+			minPreviousClicks: params.minPreviousClicks,
+			threshold: params.threshold
+		});
+		return {
+			results,
+			meta: { total: results.length }
+		};
+	}
+});
+function percentDifference(current, previous) {
+	if (previous === 0) return current > 0 ? 100 : 0;
+	return (current - previous) / previous * 100;
+}
+function str$1(v) {
+	return v == null ? "" : String(v);
+}
+function parseJsonList(v) {
+	if (Array.isArray(v)) return v;
+	if (typeof v === "string" && v.length > 0) {
+		const parsed = JSON.parse(v);
+		return Array.isArray(parsed) ? parsed : [];
+	}
+	return [];
+}
+function analyzeMovers(input, options = {}) {
+	const { changeThreshold = .2, minImpressions = 50, sortBy = "clicksChange" } = options;
+	const normFactor = input.normalizationFactor ?? 1;
+	const baselineMap = buildPeriodMap(input.previous, (r) => r.query, (r) => ({
+		clicks: num(r.clicks) / normFactor,
+		impressions: num(r.impressions) / normFactor,
+		position: num(r.position),
+		page: r.page ?? null
+	}));
+	const pageMap = /* @__PURE__ */ new Map();
+	for (const row of input.current) if (!pageMap.has(row.query) && row.page) pageMap.set(row.query, row.page);
+	for (const row of input.previous) if (!pageMap.has(row.query) && row.page) pageMap.set(row.query, row.page);
+	const rising = [];
+	const declining = [];
+	const stable = [];
+	for (const row of input.current) {
+		const impressions = num(row.impressions);
+		const clicks = num(row.clicks);
+		const position = num(row.position);
+		if (impressions < minImpressions) continue;
+		const baseline = baselineMap.get(row.query) || {
+			clicks: 0,
+			impressions: 0,
+			position: 0,
+			page: null
+		};
+		const clicksChangePercent = percentDifference(clicks, baseline.clicks);
+		const impressionsChangePercent = percentDifference(impressions, baseline.impressions);
+		const data = {
+			keyword: row.query,
+			page: pageMap.get(row.query) ?? null,
+			recentClicks: clicks,
+			recentImpressions: impressions,
+			recentPosition: position,
+			baselineClicks: Math.round(baseline.clicks),
+			baselineImpressions: Math.round(baseline.impressions),
+			baselinePosition: baseline.position,
+			clicksChange: clicks - Math.round(baseline.clicks),
+			clicksChangePercent,
+			impressionsChangePercent,
+			positionChange: position - baseline.position
+		};
+		const absChange = Math.abs(clicksChangePercent / 100);
+		if (clicksChangePercent > 0 && absChange >= changeThreshold) rising.push(data);
+		else if (clicksChangePercent < 0 && absChange >= changeThreshold) declining.push(data);
+		else stable.push(data);
+	}
+	const sortFn = (a, b) => {
+		switch (sortBy) {
+			case "clicks": return b.recentClicks - a.recentClicks;
+			case "impressions": return b.recentImpressions - a.recentImpressions;
+			case "clicksChange": return Math.abs(b.clicksChangePercent) - Math.abs(a.clicksChangePercent);
+			case "impressionsChange": return Math.abs(b.impressionsChangePercent) - Math.abs(a.impressionsChangePercent);
+			case "positionChange": return Math.abs(b.positionChange) - Math.abs(a.positionChange);
+			default: return Math.abs(b.clicksChangePercent) - Math.abs(a.clicksChangePercent);
+		}
+	};
+	rising.sort(sortFn);
+	declining.sort(sortFn);
+	stable.sort((a, b) => b.recentClicks - a.recentClicks);
+	return {
+		rising,
+		declining,
+		stable
+	};
+}
+defineAnalyzer({
+	id: "movers",
+	buildSql(params) {
+		const { current: cur, previous: prev } = comparisonOf(params);
+		const minImpressions = params.minImpressions ?? 50;
+		const changeThreshold = params.changeThreshold ?? .2;
+		const limit = params.limit ?? 2e3;
+		return {
+			sql: `
+      WITH cur AS (
+        SELECT
+          query, url,
+          ${METRIC_EXPR.clicks} AS clicks,
+          ${METRIC_EXPR.impressions} AS impressions,
+          ${METRIC_EXPR.position} AS position
+        FROM read_parquet({{FILES}}, union_by_name = true)
+        WHERE date >= ? AND date <= ?
+        GROUP BY query, url
+      ),
+      prev AS (
+        SELECT
+          query, url,
+          ${METRIC_EXPR.clicks} AS clicks,
+          ${METRIC_EXPR.impressions} AS impressions,
+          ${METRIC_EXPR.position} AS position
+        FROM read_parquet({{FILES_PREV}}, union_by_name = true)
+        WHERE date >= ? AND date <= ?
+        GROUP BY query, url
+      ),
+      weekly AS (
+        SELECT query, url, date_trunc('week', CAST(date AS DATE)) AS week,
+          ${METRIC_EXPR.clicks} AS clicks,
+          ${METRIC_EXPR.impressions} AS impressions
+        FROM (
+          SELECT query, url, date, clicks, impressions
+          FROM read_parquet({{FILES}}, union_by_name = true)
+          WHERE date >= ? AND date <= ?
+          UNION ALL
+          SELECT query, url, date, clicks, impressions
+          FROM read_parquet({{FILES_PREV}}, union_by_name = true)
+          WHERE date >= ? AND date <= ?
+        )
+        GROUP BY query, url, week
+      ),
+      series_by_entity AS (
+        SELECT query, url, to_json(list({
+          'week': strftime(week, '%Y-%m-%d'),
+          'clicks': clicks,
+          'impressions': impressions
+        } ORDER BY week)) AS seriesJson
+        FROM weekly GROUP BY query, url
+      ),
+      joined AS (
+        SELECT
+          c.query AS keyword,
+          c.url AS page,
+          c.clicks AS recentClicks,
+          c.impressions AS recentImpressions,
+          c.position AS recentPosition,
+          COALESCE(p.clicks, 0.0) AS baselineClicks,
+          COALESCE(p.impressions, 0.0) AS baselineImpressions,
+          COALESCE(p.position, 0.0) AS baselinePosition,
+          (c.clicks - COALESCE(p.clicks, 0.0)) AS clicksChange,
+          CASE
+            WHEN COALESCE(p.clicks, 0.0) = 0 THEN CASE WHEN c.clicks > 0 THEN 100.0 ELSE 0.0 END
+            ELSE (c.clicks - p.clicks) * 100.0 / p.clicks
+          END AS clicksChangePercent,
+          CASE
+            WHEN COALESCE(p.impressions, 0.0) = 0 THEN CASE WHEN c.impressions > 0 THEN 100.0 ELSE 0.0 END
+            ELSE (c.impressions - p.impressions) * 100.0 / p.impressions
+          END AS impressionsChangePercent,
+          (c.position - COALESCE(p.position, 0.0)) AS positionChange,
+          s.seriesJson
+        FROM cur c
+        LEFT JOIN prev p ON c.query = p.query AND c.url = p.url
+        LEFT JOIN series_by_entity s ON c.query = s.query AND c.url = s.url
+        WHERE c.impressions >= ?
+      )
+      SELECT *,
+        CASE
+          WHEN clicksChangePercent > 0 AND ABS(clicksChangePercent) / 100.0 >= ? THEN 'rising'
+          WHEN clicksChangePercent < 0 AND ABS(clicksChangePercent) / 100.0 >= ? THEN 'declining'
+          ELSE 'stable'
+        END AS direction
+      FROM joined
+      ORDER BY ABS(clicksChangePercent) DESC
+      LIMIT ${Number(limit)}
+    `,
+			params: [
+				cur.startDate,
+				cur.endDate,
+				prev.startDate,
+				prev.endDate,
+				cur.startDate,
+				cur.endDate,
+				prev.startDate,
+				prev.endDate,
+				minImpressions,
+				changeThreshold,
+				changeThreshold
+			],
+			current: {
+				table: "page_keywords",
+				partitions: enumeratePartitions(cur.startDate, cur.endDate)
+			},
+			previous: {
+				table: "page_keywords",
+				partitions: enumeratePartitions(prev.startDate, prev.endDate)
+			}
+		};
+	},
+	reduceSql(rows) {
+		const normalized = (Array.isArray(rows) ? rows : []).map((r) => ({
+			keyword: str$1(r.keyword),
+			page: r.page == null ? null : str$1(r.page),
+			recentClicks: num(r.recentClicks),
+			recentImpressions: num(r.recentImpressions),
+			recentPosition: num(r.recentPosition),
+			baselineClicks: Math.round(num(r.baselineClicks)),
+			baselineImpressions: Math.round(num(r.baselineImpressions)),
+			baselinePosition: num(r.baselinePosition),
+			clicksChange: num(r.clicksChange),
+			clicksChangePercent: num(r.clicksChangePercent),
+			impressionsChangePercent: num(r.impressionsChangePercent),
+			positionChange: num(r.positionChange),
+			direction: str$1(r.direction),
+			series: parseJsonList(r.seriesJson).map((s) => ({
+				week: str$1(s.week),
+				clicks: num(s.clicks),
+				impressions: num(s.impressions)
+			}))
+		}));
+		const rising = normalized.filter((r) => r.direction === "rising");
+		const declining = normalized.filter((r) => r.direction === "declining");
+		const stable = normalized.filter((r) => r.direction === "stable");
+		const combined = [...rising, ...declining];
+		return {
+			results: combined,
+			meta: {
+				total: combined.length,
+				rising: rising.length,
+				declining: declining.length,
+				stable: stable.length
+			}
+		};
+	},
+	buildRows(params) {
+		const { current, previous } = comparisonOf(params);
+		return {
+			current: keywordsQueryState(current, params.limit),
+			previous: keywordsQueryState(previous, params.limit)
+		};
+	},
+	reduceRows(rows, params) {
+		const map = rows && !Array.isArray(rows) ? rows : {
+			current: [],
+			previous: []
+		};
+		const result = analyzeMovers({
+			current: map.current ?? [],
+			previous: map.previous ?? []
+		}, {
+			changeThreshold: params.changeThreshold,
+			minImpressions: params.minImpressions
+		});
+		return {
+			results: [...result.rising.map((r) => ({
+				...r,
+				direction: "rising"
+			})), ...result.declining.map((r) => ({
+				...r,
+				direction: "declining"
+			}))],
+			meta: {
+				rising: result.rising.length,
+				declining: result.declining.length
+			}
+		};
+	}
+});
+const DEFAULT_LIMIT = 1e3;
+const MAX_LIMIT = 5e4;
+function clampLimit(limit, fallback = DEFAULT_LIMIT) {
+	const n = Number(limit ?? fallback);
+	if (!Number.isFinite(n) || n <= 0) return fallback;
+	return Math.min(n, MAX_LIMIT);
+}
+function clampOffset(offset) {
+	const n = Number(offset ?? 0);
+	if (!Number.isFinite(n) || n < 0) return 0;
+	return Math.floor(n);
+}
+function paginateClause(input) {
+	const l = clampLimit(input.limit);
+	const o = clampOffset(input.offset);
+	return o > 0 ? `LIMIT ${l} OFFSET ${o}` : `LIMIT ${l}`;
+}
+function paginateInMemory(rows, input) {
+	const l = clampLimit(input.limit, rows.length);
+	const o = clampOffset(input.offset);
+	return rows.slice(o, o + l);
+}
+const EXPECTED_CTR_BY_POSITION = {
+	1: .3,
+	2: .15,
+	3: .1,
+	4: .07,
+	5: .05,
+	6: .04,
+	7: .03,
+	8: .025,
+	9: .02,
+	10: .015
+};
+function getExpectedCtr(position) {
+	return EXPECTED_CTR_BY_POSITION[Math.round(Math.max(1, Math.min(position, 10)))] || .01;
+}
+function calculatePositionScore(position) {
+	if (position <= 3) return .2;
+	if (position > 50) return .1;
+	const distance = Math.abs(position - 11);
+	return Math.max(0, 1 - distance / 15);
+}
+function calculateImpressionScore(impressions) {
+	if (impressions <= 0) return 0;
+	return Math.min(Math.log10(impressions) / 5, 1);
+}
+function calculateCtrGapScore(actualCtr, position) {
+	const expectedCtr = getExpectedCtr(position);
+	if (actualCtr >= expectedCtr) return 0;
+	const gap = expectedCtr - actualCtr;
+	return Math.min(gap / expectedCtr, 1);
+}
+const sortResults$1 = createMetricSorter("opportunityScore", {
+	opportunityScore: "desc",
+	potentialClicks: "desc",
+	impressions: "desc",
+	position: "asc"
+});
+const opportunityAnalyzer = defineAnalyzer({
+	id: "opportunity",
+	buildSql(params) {
+		const { startDate, endDate } = periodOf(params);
+		const minImpressions = params.minImpressions ?? 100;
+		const w1 = 1;
+		const w2 = 1;
+		const w3 = 1;
+		const totalW = w1 + w2 + w3;
+		const limit = params.limit ?? 1e3;
+		return {
+			sql: `
+    WITH agg AS (
+      SELECT
+        query AS keyword,
+        url AS page,
+        ${METRIC_EXPR.clicks} AS clicks,
+        ${METRIC_EXPR.impressions} AS impressions,
+        ${METRIC_EXPR.ctr} AS ctr,
+        ${METRIC_EXPR.position} AS position
+      FROM read_parquet({{FILES}}, union_by_name = true)
+      WHERE date >= ? AND date <= ?
+      GROUP BY query, url
+      HAVING SUM(impressions) >= ?
+    ),
+    scored AS (
+      SELECT
+        keyword, page, clicks, impressions, ctr, position,
+        CASE
+          WHEN position <= 3 THEN 0.2
+          WHEN position > 50 THEN 0.1
+          ELSE GREATEST(0.0, 1.0 - ABS(position - 11.0) / 15.0)
+        END AS positionScore,
+        CASE WHEN impressions <= 0 THEN 0.0 ELSE LEAST(LOG10(impressions) / 5.0, 1.0) END AS impressionScore,
+        CASE CAST(ROUND(GREATEST(LEAST(position, 10.0), 1.0)) AS INTEGER)
+          WHEN 1 THEN 0.30
+          WHEN 2 THEN 0.15
+          WHEN 3 THEN 0.10
+          WHEN 4 THEN 0.07
+          WHEN 5 THEN 0.05
+          WHEN 6 THEN 0.04
+          WHEN 7 THEN 0.03
+          WHEN 8 THEN 0.025
+          WHEN 9 THEN 0.02
+          WHEN 10 THEN 0.015
+          ELSE 0.01
+        END AS expectedCtr
+      FROM agg
+    ),
+    gapped AS (
+      SELECT
+        *,
+        CASE WHEN ctr >= expectedCtr THEN 0.0 ELSE LEAST((expectedCtr - ctr) / expectedCtr, 1.0) END AS ctrGapScore
+      FROM scored
+    )
+    SELECT
+      keyword, page, clicks, impressions, ctr, position,
+      CAST(ROUND(POWER(
+        POWER(positionScore, ${w1}) * POWER(impressionScore, ${w2}) * POWER(ctrGapScore, ${w3}),
+        1.0 / ${totalW}
+      ) * 100) AS DOUBLE) AS opportunityScore,
+      CAST(ROUND(impressions * (
+        CASE CAST(ROUND(GREATEST(LEAST(position, 3.0), 1.0)) AS INTEGER)
+          WHEN 1 THEN 0.30
+          WHEN 2 THEN 0.15
+          WHEN 3 THEN 0.10
+          ELSE 0.10
+        END
+      )) AS DOUBLE) AS potentialClicks,
+      positionScore, impressionScore, ctrGapScore
+    FROM gapped
+    ORDER BY opportunityScore DESC
+    ${paginateClause({
+				limit,
+				offset: params.offset
+			})}
+  `,
+			params: [
+				startDate,
+				endDate,
+				minImpressions
+			],
+			current: {
+				table: "page_keywords",
+				partitions: enumeratePartitions(startDate, endDate)
+			}
+		};
+	},
+	reduceSql(rows) {
+		const arr = Array.isArray(rows) ? rows : [];
+		return {
+			results: arr.map((r) => ({
+				keyword: r.keyword == null ? "" : String(r.keyword),
+				page: r.page == null ? null : String(r.page),
+				clicks: num(r.clicks),
+				impressions: num(r.impressions),
+				ctr: num(r.ctr),
+				position: num(r.position),
+				opportunityScore: num(r.opportunityScore),
+				potentialClicks: num(r.potentialClicks),
+				factors: {
+					positionScore: num(r.positionScore),
+					impressionScore: num(r.impressionScore),
+					ctrGapScore: num(r.ctrGapScore)
+				}
+			})),
+			meta: { total: arr.length }
+		};
+	},
+	buildRows(params) {
+		return { keywords: keywordsQueryState(periodOf(params), params.limit) };
+	},
+	reduceRows(rows, params) {
+		const keywords = (Array.isArray(rows) ? rows : []) ?? [];
+		const minImpressions = params.minImpressions ?? 100;
+		const positionWeight = 1;
+		const impressionsWeight = 1;
+		const ctrGapWeight = 1;
+		const sortBy = "opportunityScore";
+		const results = [];
+		for (const row of keywords) {
+			const impressions = num(row.impressions);
+			const position = num(row.position);
+			const ctr = num(row.ctr);
+			const clicks = num(row.clicks);
+			if (impressions < minImpressions) continue;
+			const positionScore = calculatePositionScore(position);
+			const impressionScore = calculateImpressionScore(impressions);
+			const ctrGapScore = calculateCtrGapScore(ctr, position);
+			const geometricMean = (positionScore ** positionWeight * impressionScore ** impressionsWeight * ctrGapScore ** ctrGapWeight) ** (1 / (positionWeight + impressionsWeight + ctrGapWeight));
+			const opportunityScore = Math.round(geometricMean * 100);
+			const targetCtr = getExpectedCtr(Math.min(3, position));
+			const potentialClicks = Math.round(impressions * targetCtr);
+			results.push({
+				keyword: row.query,
+				page: row.page ?? null,
+				clicks,
+				impressions,
+				ctr,
+				position,
+				opportunityScore,
+				potentialClicks,
+				factors: {
+					positionScore,
+					impressionScore,
+					ctrGapScore
+				}
+			});
+		}
+		const sorted = sortResults$1(results, sortBy);
+		const paged = paginateInMemory(sorted, {
+			limit: params.limit,
+			offset: params.offset
+		});
+		return {
+			results: paged,
+			meta: {
+				total: sorted.length,
+				returned: paged.length
+			}
+		};
+	}
+});
+function str(v) {
+	return v == null ? "" : String(v);
+}
+function bool(v) {
+	return v === true || v === 1 || v === "true";
+}
+function calculateCV(values) {
+	if (values.length === 0) return 0;
+	const mean = values.reduce((a, b) => a + b, 0) / values.length;
+	if (mean === 0) return 0;
+	const variance = values.reduce((sum, v) => sum + (v - mean) ** 2, 0) / values.length;
+	return Math.min(Math.sqrt(variance) / mean, 1);
+}
+function analyzeSeasonality(dates, options = {}) {
+	const { metric = "clicks" } = options;
+	if (dates.length === 0) return {
+		hasSeasonality: false,
+		strength: 0,
+		peakMonths: [],
+		troughMonths: [],
+		monthlyBreakdown: [],
+		insufficientData: true
+	};
+	const monthlyMap = /* @__PURE__ */ new Map();
+	for (const row of dates) {
+		const month = row.date.substring(0, 7);
+		const value = metric === "clicks" ? row.clicks : row.impressions;
+		monthlyMap.set(month, (monthlyMap.get(month) || 0) + value);
+	}
+	const months = Array.from(monthlyMap.keys()).sort();
+	const values = months.map((m) => monthlyMap.get(m) || 0);
+	const insufficientData = months.length < 12;
+	const totalValue = values.reduce((a, b) => a + b, 0);
+	const avgValue = values.length > 0 ? totalValue / values.length : 0;
+	const monthlyBreakdown = months.map((month, i) => {
+		const value = values[i] ?? 0;
+		const vsAverage = avgValue > 0 ? value / avgValue : 0;
+		return {
+			month,
+			value,
+			vsAverage,
+			isPeak: vsAverage > 1.5,
+			isTrough: vsAverage < .5
+		};
+	});
+	const peakMonths = [...new Set(monthlyBreakdown.filter((m) => m.isPeak).map((m) => m.month.substring(5, 7)))];
+	const troughMonths = [...new Set(monthlyBreakdown.filter((m) => m.isTrough).map((m) => m.month.substring(5, 7)))];
+	const strength = calculateCV(values);
+	return {
+		hasSeasonality: peakMonths.length > 0 || troughMonths.length > 0 || strength > .3,
+		strength,
+		peakMonths,
+		troughMonths,
+		monthlyBreakdown,
+		insufficientData
+	};
+}
+defineAnalyzer({
+	id: "seasonality",
+	buildSql(params) {
+		const { startDate, endDate } = periodOf(params);
+		return {
+			sql: `
+      WITH monthly AS (
+        SELECT
+          strftime(date, '%Y-%m') AS month,
+          CAST(SUM(${params.metric === "impressions" ? "impressions" : "clicks"}) AS DOUBLE) AS value
+        FROM read_parquet({{FILES}}, union_by_name = true)
+        WHERE date >= ? AND date <= ?
+        GROUP BY month
+      ),
+      stats AS (
+        SELECT
+          AVG(value) AS avg_val,
+          COALESCE(STDDEV_POP(value), 0.0) AS std_val,
+          CAST(COUNT(*) AS DOUBLE) AS month_count
+        FROM monthly
+      )
+      SELECT
+        m.month AS month,
+        m.value AS value,
+        CASE WHEN s.avg_val > 0 THEN m.value / s.avg_val ELSE 0.0 END AS vsAverage,
+        (s.avg_val > 0 AND m.value / s.avg_val > 1.5) AS isPeak,
+        (s.avg_val > 0 AND m.value / s.avg_val < 0.5) AS isTrough,
+        CASE WHEN s.avg_val > 0 THEN LEAST(s.std_val / s.avg_val, 1.0) ELSE 0.0 END AS strength,
+        s.month_count AS monthCount
+      FROM monthly m, stats s
+      ORDER BY m.month
+    `,
+			params: [startDate, endDate],
+			current: {
+				table: "pages",
+				partitions: enumeratePartitions(startDate, endDate)
+			}
+		};
+	},
+	reduceSql(rows) {
+		const arr = Array.isArray(rows) ? rows : [];
+		const breakdown = arr.map((r) => ({
+			month: str(r.month),
+			value: num(r.value),
+			vsAverage: num(r.vsAverage),
+			isPeak: bool(r.isPeak),
+			isTrough: bool(r.isTrough)
+		}));
+		const first = arr[0];
+		const strength = first ? num(first.strength) : 0;
+		const monthCount = first ? num(first.monthCount) : 0;
+		const peakMonths = [...new Set(breakdown.filter((m) => m.isPeak).map((m) => m.month.substring(5, 7)))];
+		const troughMonths = [...new Set(breakdown.filter((m) => m.isTrough).map((m) => m.month.substring(5, 7)))];
+		const hasSeasonality = peakMonths.length > 0 || troughMonths.length > 0 || strength > .3;
+		const insufficientData = monthCount < 12;
+		return {
+			results: breakdown,
+			meta: {
+				total: breakdown.length,
+				hasSeasonality,
+				strength,
+				peakMonths,
+				troughMonths,
+				insufficientData
+			}
+		};
+	},
+	buildRows(params) {
+		return { dates: datesQueryState(periodOf(params), params.limit) };
+	},
+	reduceRows(rows, params) {
+		const result = analyzeSeasonality(Array.isArray(rows) ? rows : [], { metric: params.metric });
+		return {
+			results: result.monthlyBreakdown,
+			meta: { strength: result.strength }
+		};
+	}
+});
+const sortResults = createSorter((item, metric) => item[metric], "potentialClicks");
+function analyzeStrikingDistance(keywords, options = {}) {
+	const { minPosition = 4, maxPosition = 20, minImpressions = 100, maxCtr = .05, sortBy = "potentialClicks", sortOrder = "desc" } = options;
+	const results = [];
+	for (const row of keywords) {
+		const position = num(row.position);
+		const impressions = num(row.impressions);
+		const ctr = num(row.ctr);
+		const clicks = num(row.clicks);
+		if (position < minPosition || position > maxPosition) continue;
+		if (impressions < minImpressions) continue;
+		if (ctr > maxCtr) continue;
+		const potentialClicks = Math.round(impressions * .15);
+		results.push({
+			keyword: row.query,
+			page: row.page ?? null,
+			clicks,
+			impressions,
+			ctr,
+			position,
+			potentialClicks
+		});
+	}
+	return sortResults(results, sortBy, sortOrder);
+}
+function typedQuery(state) {
+	return { state };
+}
+function isTypedQuery(value) {
+	return "state" in value;
+}
+async function queryRows(source, query) {
+	const state = isTypedQuery(query) ? query.state : query;
+	return await source.queryRows(state);
+}
+async function queryComparisonRows(source, current, previous) {
+	const [currentRows, previousRows] = await Promise.all([queryRows(source, current), queryRows(source, previous)]);
+	return {
+		current: currentRows,
+		previous: previousRows
+	};
+}
+function keywordQuery(period, limit) {
+	return typedQuery(keywordsQueryState(period, limit));
+}
+function pageQuery(period, limit) {
+	return typedQuery(pagesQueryState(period, limit));
+}
+function dateQuery(period, limit) {
+	return typedQuery(datesQueryState(period, limit));
+}
+function definePortableAnalyzer(definition) {
+	return definition;
+}
+async function runPortableAnalyzer(source, definition, input, options, limit = 25e3) {
+	const requiredQueries = definition.requiredQueries(input, limit);
+	const entries = Object.entries(requiredQueries);
+	const resolvedRows = await Promise.all(entries.map(async ([key, spec]) => [key, await queryRows(source, spec)]));
+	return definition.run(Object.fromEntries(resolvedRows), options);
+}
+const PORTABLE_ANALYZERS = {
+	strikingDistance: definePortableAnalyzer({
+		requiredQueries: (period, limit) => ({ keywords: keywordQuery(period, limit) }),
+		run: ({ keywords }, options) => analyzeStrikingDistance(keywords, options)
+	}),
+	opportunity: definePortableAnalyzer({
+		requiredQueries: (period, limit) => ({ keywords: keywordQuery(period, limit) }),
+		run: ({ keywords }, options) => {
+			const { results } = opportunityAnalyzer.rows.reduce(keywords, { params: {
+				type: "opportunity",
+				minImpressions: options?.minImpressions
+			} });
+			return results;
+		}
+	}),
+	brandSegmentation: definePortableAnalyzer({
+		requiredQueries: (period, limit) => ({ keywords: keywordQuery(period, limit) }),
+		run: ({ keywords }, options) => analyzeBrandSegmentation(keywords, options)
+	}),
+	pageConcentration: definePortableAnalyzer({
+		requiredQueries: (period, limit) => ({ pages: pageQuery(period, limit) }),
+		run: ({ pages }, options) => analyzePageConcentration(pages, options)
+	}),
+	keywordConcentration: definePortableAnalyzer({
+		requiredQueries: (period, limit) => ({ keywords: keywordQuery(period, limit) }),
+		run: ({ keywords }, options) => analyzeKeywordConcentration(keywords, options)
+	}),
+	clustering: definePortableAnalyzer({
+		requiredQueries: (period, limit) => ({ keywords: keywordQuery(period, limit) }),
+		run: ({ keywords }, options) => analyzeClustering(keywords, options)
+	}),
+	seasonality: definePortableAnalyzer({
+		requiredQueries: (period, limit) => ({ dates: dateQuery(period, limit) }),
+		run: ({ dates }, options) => analyzeSeasonality(dates, options)
+	}),
+	decay: definePortableAnalyzer({
+		requiredQueries: (periods, limit) => ({
+			current: pageQuery(periods.current, limit),
+			previous: pageQuery(periods.previous, limit)
+		}),
+		run: ({ current, previous }, options) => analyzeDecay({
+			current,
+			previous
+		}, options)
+	}),
+	movers: definePortableAnalyzer({
+		requiredQueries: (periods, limit) => ({
+			current: keywordQuery(periods.current, limit),
+			previous: keywordQuery(periods.previous, limit)
+		}),
+		run: ({ current, previous }, options) => analyzeMovers({
+			current,
+			previous
+		}, options)
+	})
+};
+async function queryAnalyticsFromSource(source, period, options = {}) {
+	const limit = options.limit ?? 25e3;
+	const [keywords, pages, dates] = await Promise.all([
+		queryRows(source, keywordQuery(period, limit)),
+		queryRows(source, pageQuery(period, limit)),
+		queryRows(source, dateQuery(period, limit))
+	]);
+	return {
+		keywords,
+		pages,
+		dates
+	};
+}
+async function queryComparisonFromSource(source, periods, options = {}) {
+	const [current, previous] = await Promise.all([queryAnalyticsFromSource(source, periods.current, options), queryAnalyticsFromSource(source, periods.previous, options)]);
+	return {
+		current,
+		previous
+	};
+}
+async function analyzeStrikingDistanceFromSource(source, period, options) {
+	return runPortableAnalyzer(source, PORTABLE_ANALYZERS.strikingDistance, period, options);
+}
+async function analyzeOpportunityFromSource(source, period, options) {
+	return runPortableAnalyzer(source, PORTABLE_ANALYZERS.opportunity, period, options);
+}
+async function analyzeBrandSegmentationFromSource(source, period, options) {
+	return runPortableAnalyzer(source, PORTABLE_ANALYZERS.brandSegmentation, period, options);
+}
+async function analyzePageConcentrationFromSource(source, period, options) {
+	return runPortableAnalyzer(source, PORTABLE_ANALYZERS.pageConcentration, period, options);
+}
+async function analyzeKeywordConcentrationFromSource(source, period, options) {
+	return runPortableAnalyzer(source, PORTABLE_ANALYZERS.keywordConcentration, period, options);
+}
+async function analyzeClusteringFromSource(source, period, options) {
+	return runPortableAnalyzer(source, PORTABLE_ANALYZERS.clustering, period, options);
+}
+async function analyzeSeasonalityFromSource(source, period, options) {
+	return runPortableAnalyzer(source, PORTABLE_ANALYZERS.seasonality, period, options);
+}
+async function analyzeDecayFromSource(source, periods, options) {
+	return runPortableAnalyzer(source, PORTABLE_ANALYZERS.decay, periods, options);
+}
+async function analyzeMoversFromSource(source, periods, options) {
+	return runPortableAnalyzer(source, PORTABLE_ANALYZERS.movers, periods, options);
+}
+export { AnalyzerCapabilityError, ENGINE_QUERY_CAPABILITIES, GSC_API_CAPABILITIES, IN_MEMORY_DEFAULT_CAPABILITIES, analyzeBrandSegmentationFromSource, analyzeClusteringFromSource, analyzeDecayFromSource, analyzeFromSource, analyzeKeywordConcentrationFromSource, analyzeMoversFromSource, analyzeOpportunityFromSource, analyzePageConcentrationFromSource, analyzeSeasonalityFromSource, analyzeStrikingDistanceFromSource, collectRows as collectGscRows, createBrowserQuerySource, createEngineQuerySource, createGscApiQuerySource, createInMemoryQuerySource, createSqliteQuerySource, fetchGscDaily, fetchGscTopN, isSqlQuerySource, queryAnalyticsFromSource, queryComparisonFromSource, queryComparisonRows, queryRows, runAnalyzerWithEngine, typedQuery };