gscdump 0.1.3 → 0.3.0

package/dist/analysis/index.mjs

@@ -0,0 +1,872 @@
+//#region src/analysis/types.ts
+/** Coerce nullable number to number, defaulting to 0 */
+function num(value) {
+	return value ?? 0;
+}
+/** Create a generic sorter for any metric type */
+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);
+	};
+}
+
+//#endregion
+//#region src/analysis/brand.ts
+/**
+* Segments keywords into brand and non-brand based on provided brand terms.
+*/
+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)
+		}
+	};
+}
+
+//#endregion
+//#region src/analysis/clustering.ts
+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"
+];
+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(/\s+/).filter(Boolean);
+	if (words.length < wordCount + 1) return null;
+	return words.slice(0, wordCount).join(" ");
+}
+/**
+* Clusters keywords by intent prefix or common word prefix.
+*/
+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))
+	};
+}
+
+//#endregion
+//#region src/analysis/concentration.ts
+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);
+}
+/**
+* Analyzes traffic concentration across items (pages or keywords).
+*/
+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
+	};
+}
+/**
+* Page concentration analysis.
+*/
+function analyzePageConcentration(pages, options) {
+	return analyzeConcentration(pages.map((p) => ({
+		key: p.page,
+		clicks: num(p.clicks)
+	})), options);
+}
+/**
+* Keyword concentration analysis.
+*/
+function analyzeKeywordConcentration(keywords, options) {
+	return analyzeConcentration(keywords.map((k) => ({
+		key: k.query,
+		clicks: num(k.clicks)
+	})), options);
+}
+
+//#endregion
+//#region src/analysis/decay.ts
+const SORT_ORDER$1 = {
+	lostClicks: "desc",
+	declinePercent: "desc",
+	currentClicks: "asc"
+};
+const sortResults$2 = createSorter((item, metric) => item[metric], "lostClicks");
+/**
+* Identifies "decaying" content - pages that have lost significant traffic.
+*/
+function analyzeDecay(input, options = {}) {
+	const { minPreviousClicks = 50, threshold = .2, sortBy = "lostClicks" } = options;
+	const currentMap = /* @__PURE__ */ new Map();
+	for (const row of input.current) currentMap.set(row.page, {
+		clicks: num(row.clicks),
+		position: num(row.position)
+	});
+	const previousMap = /* @__PURE__ */ new Map();
+	for (const row of input.previous) {
+		const clicks$1 = num(row.clicks);
+		if (clicks$1 >= minPreviousClicks) previousMap.set(row.page, {
+			clicks: clicks$1,
+			position: num(row.position)
+		});
+	}
+	const results = [];
+	for (const [page$1, prev] of previousMap) {
+		const curr = currentMap.get(page$1) || {
+			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: page$1,
+			currentClicks: curr.clicks,
+			previousClicks: prev.clicks,
+			lostClicks,
+			declinePercent,
+			currentPosition: curr.position,
+			previousPosition: prev.position,
+			positionDrop: curr.position - prev.position
+		});
+	}
+	return sortResults$2(results, sortBy, SORT_ORDER$1[sortBy]);
+}
+
+//#endregion
+//#region src/query/resolver.ts
+const DATE_OPERATORS = [
+	"gte",
+	"gt",
+	"lte",
+	"lt",
+	"between"
+];
+const METRIC_OPERATORS = [
+	"metricGte",
+	"metricGt",
+	"metricLte",
+	"metricLt",
+	"metricBetween"
+];
+const SPECIAL_OPERATORS = ["topLevel"];
+const QUERY_PARAMS = ["searchType"];
+function isMetricOperator(op) {
+	return METRIC_OPERATORS.includes(op);
+}
+function isSpecialOperator(op) {
+	return SPECIAL_OPERATORS.includes(op);
+}
+function isDateOperator(op) {
+	return DATE_OPERATORS.includes(op);
+}
+function isQueryParam(dim) {
+	return QUERY_PARAMS.includes(dim);
+}
+function addDays(dateStr, days) {
+	const d = new Date(dateStr);
+	d.setDate(d.getDate() + days);
+	return d.toISOString().split("T")[0];
+}
+function extractSpecialFilters(filter) {
+	if (!filter) return {};
+	let startDate;
+	let endDate;
+	let searchType$1;
+	const otherFilters = [];
+	const cleanedNestedGroups = [];
+	for (const f of filter._filters) if (f.dimension === "date" && isDateOperator(f.operator)) switch (f.operator) {
+		case "gte":
+			startDate = f.expression;
+			break;
+		case "gt":
+			startDate = addDays(f.expression, 1);
+			break;
+		case "lte":
+			endDate = f.expression;
+			break;
+		case "lt":
+			endDate = addDays(f.expression, -1);
+			break;
+		case "between":
+			startDate = f.expression;
+			endDate = f.expression2;
+			break;
+	}
+	else if (isQueryParam(f.dimension)) {
+		if (f.dimension === "searchType") searchType$1 = f.expression;
+	} else if (isMetricOperator(f.operator) || isSpecialOperator(f.operator)) otherFilters.push(f);
+	else otherFilters.push(f);
+	if (filter._nestedGroups) for (const nested of filter._nestedGroups) {
+		const extracted = extractSpecialFilters(nested);
+		if (extracted.startDate) startDate = extracted.startDate;
+		if (extracted.endDate) endDate = extracted.endDate;
+		if (extracted.searchType) searchType$1 = extracted.searchType;
+		if (extracted.dimensionFilter) cleanedNestedGroups.push(extracted.dimensionFilter);
+	}
+	const dimensionFilter = otherFilters.length > 0 || cleanedNestedGroups.length > 0 ? {
+		...filter,
+		_filters: otherFilters,
+		_nestedGroups: cleanedNestedGroups.length > 0 ? cleanedNestedGroups : void 0
+	} : void 0;
+	return {
+		startDate,
+		endDate,
+		searchType: searchType$1,
+		dimensionFilter
+	};
+}
+function resolveToBody(state) {
+	const { startDate, endDate, searchType: searchType$1, dimensionFilter } = extractSpecialFilters(state.filter);
+	if (!startDate || !endDate) throw new Error("Date range required: use .where(between(date, start, end)) or .where(and(gte(date, start), lte(date, end)))");
+	const body = {
+		dimensions: state.dimensions,
+		startDate,
+		endDate
+	};
+	if (searchType$1) body.searchType = searchType$1;
+	if (state.rowLimit) body.rowLimit = state.rowLimit;
+	if (state.startRow) body.startRow = state.startRow;
+	const filterGroups = resolveFilter(dimensionFilter);
+	if (filterGroups.length > 0) body.dimensionFilterGroups = filterGroups;
+	return body;
+}
+function isApiFilter(f) {
+	return !isMetricOperator(f.operator) && !isSpecialOperator(f.operator);
+}
+function resolveFilter(filter) {
+	if (!filter) return [];
+	const groups = [];
+	const groupType = filter._groupType ?? "and";
+	const apiFilters = filter._filters.filter(isApiFilter);
+	if (groupType === "or") {
+		if (apiFilters.length > 0) groups.push({
+			groupType: "or",
+			filters: apiFilters.map((f) => ({
+				dimension: f.dimension,
+				operator: f.operator,
+				expression: f.expression
+			}))
+		});
+	} else if (apiFilters.length > 0) groups.push({ filters: apiFilters.map((f) => ({
+		dimension: f.dimension,
+		operator: f.operator,
+		expression: f.expression
+	})) });
+	if (filter._nestedGroups) for (const nested of filter._nestedGroups) groups.push(...resolveFilter(nested));
+	return groups;
+}
+
+//#endregion
+//#region src/query/builder.ts
+function isDimensionString(v) {
+	return typeof v === "string";
+}
+function isMetricColumn(v) {
+	return typeof v === "object" && v !== null && "metric" in v;
+}
+function isDimensionColumn(v) {
+	return typeof v === "object" && v !== null && "dimension" in v && !("metric" in v);
+}
+function createBuilder(state) {
+	return {
+		select(...args) {
+			const dimensions = [];
+			const metrics = [];
+			for (const arg of args) if (isDimensionString(arg)) dimensions.push(arg);
+			else if (isDimensionColumn(arg)) dimensions.push(arg.dimension);
+			else if (isMetricColumn(arg)) metrics.push(arg.metric);
+			return createBuilder({
+				...state,
+				dimensions,
+				metrics: metrics.length > 0 ? metrics : void 0
+			});
+		},
+		where(filter) {
+			return createBuilder({
+				...state,
+				filter
+			});
+		},
+		orderBy(col, dir) {
+			const column = isMetricColumn(col) ? col.metric : col.dimension;
+			return createBuilder({
+				...state,
+				orderBy: {
+					column,
+					dir
+				}
+			});
+		},
+		limit(n) {
+			return createBuilder({
+				...state,
+				rowLimit: n
+			});
+		},
+		offset(n) {
+			return createBuilder({
+				...state,
+				startRow: n
+			});
+		},
+		toBody() {
+			return resolveToBody(state);
+		},
+		getState() {
+			return { ...state };
+		}
+	};
+}
+const gsc = createBuilder({ dimensions: [] });
+
+//#endregion
+//#region src/query/columns.ts
+function createColumn(dimension) {
+	return { dimension };
+}
+function createMetricColumn(metric) {
+	return { metric };
+}
+function createQueryParam(param) {
+	return { param };
+}
+const page = createColumn("page");
+const query = createColumn("query");
+const queryCanonical = createColumn("queryCanonical");
+const device = createColumn("device");
+const country = createColumn("country");
+const searchAppearance = createColumn("searchAppearance");
+const date = createColumn("date");
+const clicks = createMetricColumn("clicks");
+const impressions = createMetricColumn("impressions");
+const ctr = createMetricColumn("ctr");
+const position = createMetricColumn("position");
+const searchType = createQueryParam("searchType");
+
+//#endregion
+//#region src/query/operators.ts
+function between(column, start, end) {
+	if ("metric" in column) return {
+		_constraints: {},
+		_filters: [{
+			dimension: column.metric,
+			operator: "metricBetween",
+			expression: String(start),
+			expression2: String(end)
+		}]
+	};
+	return {
+		_constraints: {},
+		_filters: [{
+			dimension: column.dimension,
+			operator: "between",
+			expression: String(start),
+			expression2: String(end)
+		}]
+	};
+}
+
+//#endregion
+//#region src/analysis/movers.ts
+function percentDifference(current, previous) {
+	if (previous === 0) return current > 0 ? 100 : 0;
+	return (current - previous) / previous * 100;
+}
+/**
+* Identifies movers and shakers - keywords with significant recent changes.
+*/
+function analyzeMovers(input, options = {}) {
+	const { changeThreshold = .2, minImpressions = 50, sortBy = "clicksChange" } = options;
+	const normFactor = input.normalizationFactor ?? 1;
+	const baselineMap = /* @__PURE__ */ new Map();
+	for (const row of input.previous) baselineMap.set(row.query, {
+		clicks: num(row.clicks) / normFactor,
+		impressions: num(row.impressions) / normFactor,
+		position: num(row.position),
+		page: row.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$1 = num(row.impressions);
+		const clicks$1 = num(row.clicks);
+		const position$1 = num(row.position);
+		if (impressions$1 < minImpressions) continue;
+		const baseline = baselineMap.get(row.query) || {
+			clicks: 0,
+			impressions: 0,
+			position: 0,
+			page: null
+		};
+		const clicksChangePercent = percentDifference(clicks$1, baseline.clicks);
+		const impressionsChangePercent = percentDifference(impressions$1, baseline.impressions);
+		const data = {
+			keyword: row.query,
+			page: pageMap.get(row.query) ?? null,
+			recentClicks: clicks$1,
+			recentImpressions: impressions$1,
+			recentPosition: position$1,
+			baselineClicks: Math.round(baseline.clicks),
+			baselineImpressions: Math.round(baseline.impressions),
+			baselinePosition: baseline.position,
+			clicksChange: clicks$1 - Math.round(baseline.clicks),
+			clicksChangePercent,
+			impressionsChangePercent,
+			positionChange: position$1 - 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
+	};
+}
+
+//#endregion
+//#region src/analysis/opportunity.ts
+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$1) {
+	return EXPECTED_CTR_BY_POSITION[Math.round(Math.max(1, Math.min(position$1, 10)))] || .01;
+}
+function calculatePositionScore(position$1) {
+	if (position$1 <= 3) return .2;
+	if (position$1 > 50) return .1;
+	const distance = Math.abs(position$1 - 11);
+	return Math.max(0, 1 - distance / 15);
+}
+function calculateImpressionScore(impressions$1) {
+	if (impressions$1 <= 0) return 0;
+	return Math.min(Math.log10(impressions$1) / 5, 1);
+}
+function calculateCtrGapScore(actualCtr, position$1) {
+	const expectedCtr = getExpectedCtr(position$1);
+	if (actualCtr >= expectedCtr) return 0;
+	const gap = expectedCtr - actualCtr;
+	return Math.min(gap / expectedCtr, 1);
+}
+const SORT_ORDER = {
+	opportunityScore: "desc",
+	potentialClicks: "desc",
+	impressions: "desc",
+	position: "asc"
+};
+const sortResults$1 = createSorter((item, metric) => item[metric], "opportunityScore");
+/**
+* Scores keywords by optimization opportunity.
+* Composite score combining position, impressions, and CTR gap factors.
+*/
+function analyzeOpportunity(keywords, options = {}) {
+	const { minImpressions = 100, weights = {}, sortBy = "opportunityScore" } = options;
+	const positionWeight = weights.position ?? 1;
+	const impressionsWeight = weights.impressions ?? 1;
+	const ctrGapWeight = weights.ctrGap ?? 1;
+	const results = [];
+	for (const row of keywords) {
+		const impressions$1 = num(row.impressions);
+		const position$1 = num(row.position);
+		const ctr$1 = num(row.ctr);
+		const clicks$1 = num(row.clicks);
+		if (impressions$1 < minImpressions) continue;
+		const positionScore = calculatePositionScore(position$1);
+		const impressionScore = calculateImpressionScore(impressions$1);
+		const ctrGapScore = calculateCtrGapScore(ctr$1, position$1);
+		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$1));
+		const potentialClicks = Math.round(impressions$1 * targetCtr);
+		results.push({
+			keyword: row.query,
+			page: row.page ?? null,
+			clicks: clicks$1,
+			impressions: impressions$1,
+			ctr: ctr$1,
+			position: position$1,
+			opportunityScore,
+			potentialClicks,
+			factors: {
+				positionScore,
+				impressionScore,
+				ctrGapScore
+			}
+		});
+	}
+	return sortResults$1(results, sortBy, SORT_ORDER[sortBy]);
+}
+
+//#endregion
+//#region src/analysis/seasonality.ts
+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;
+	const stdDev = Math.sqrt(variance);
+	return Math.min(stdDev / mean, 1);
+}
+/**
+* Detects seasonality patterns by analyzing monthly traffic variation.
+*/
+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];
+		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
+	};
+}
+
+//#endregion
+//#region src/analysis/striking-distance.ts
+const sortResults = createSorter((item, metric) => item[metric], "potentialClicks");
+/**
+* Finds striking distance keywords - high impressions, low CTR, position 4-20.
+* These are "quick wins" that could gain significant traffic with small ranking improvements.
+*/
+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$1 = num(row.position);
+		const impressions$1 = num(row.impressions);
+		const ctr$1 = num(row.ctr);
+		const clicks$1 = num(row.clicks);
+		if (position$1 < minPosition || position$1 > maxPosition) continue;
+		if (impressions$1 < minImpressions) continue;
+		if (ctr$1 > maxCtr) continue;
+		const potentialClicks = Math.round(impressions$1 * .15);
+		results.push({
+			keyword: row.query,
+			page: row.page ?? null,
+			clicks: clicks$1,
+			impressions: impressions$1,
+			ctr: ctr$1,
+			position: position$1,
+			potentialClicks
+		});
+	}
+	return sortResults(results, sortBy, sortOrder);
+}
+
+//#endregion
+//#region src/analysis/fetch.ts
+/** Collect all rows from async generator */
+async function collectRows(generator) {
+	const rows = [];
+	for await (const batch of generator) rows.push(...batch);
+	return rows;
+}
+/** Fetch keywords (query+page dimensions) for a period */
+async function fetchKeywordsInternal(client, siteUrl, period, limit = 25e3) {
+	const builder = gsc.select(query, page).where(between(date, period.startDate, period.endDate)).limit(limit);
+	return collectRows(client.query(siteUrl, builder));
+}
+/** Fetch pages (page dimension) for a period */
+async function fetchPagesInternal(client, siteUrl, period, limit = 25e3) {
+	const builder = gsc.select(page).where(between(date, period.startDate, period.endDate)).limit(limit);
+	return collectRows(client.query(siteUrl, builder));
+}
+/** Fetch dates (date dimension) for a period */
+async function fetchDatesInternal(client, siteUrl, period, limit = 25e3) {
+	const builder = gsc.select(date).where(between(date, period.startDate, period.endDate)).limit(limit);
+	return collectRows(client.query(siteUrl, builder));
+}
+/**
+* Query search analytics data for a single period.
+* Returns keywords, pages, and dates data.
+* API calls: 3 (one per dimension)
+*/
+async function queryAnalytics(client, siteUrl, period, options = {}) {
+	const limit = options.limit ?? 25e3;
+	const [keywords, pages, dates] = await Promise.all([
+		fetchKeywordsInternal(client, siteUrl, period, limit),
+		fetchPagesInternal(client, siteUrl, period, limit),
+		fetchDatesInternal(client, siteUrl, period, limit)
+	]);
+	return {
+		keywords,
+		pages,
+		dates
+	};
+}
+/**
+* Query search analytics data for current and previous periods.
+* Returns comparison data for all dimensions.
+* API calls: 6 (3 per period)
+*/
+async function queryComparison(client, siteUrl, periods, options = {}) {
+	const [current, previous] = await Promise.all([queryAnalytics(client, siteUrl, periods.current, options), queryAnalytics(client, siteUrl, periods.previous, options)]);
+	return {
+		current,
+		previous
+	};
+}
+const fetchKeywords = fetchKeywordsInternal;
+const fetchPages = fetchPagesInternal;
+const fetchDates = fetchDatesInternal;
+/**
+* Fetch keywords and analyze striking distance opportunities.
+* API calls: 1
+*/
+async function fetchStrikingDistance(client, siteUrl, period, options) {
+	return analyzeStrikingDistance(await fetchKeywords(client, siteUrl, period), options);
+}
+/**
+* Fetch keywords and analyze optimization opportunities.
+* API calls: 1
+*/
+async function fetchOpportunity(client, siteUrl, period, options) {
+	return analyzeOpportunity(await fetchKeywords(client, siteUrl, period), options);
+}
+/**
+* Fetch keywords and analyze brand vs non-brand segmentation.
+* API calls: 1
+*/
+async function fetchBrandSegmentation(client, siteUrl, period, options) {
+	return analyzeBrandSegmentation(await fetchKeywords(client, siteUrl, period), options);
+}
+/**
+* Fetch pages and analyze traffic concentration.
+* API calls: 1
+*/
+async function fetchPageConcentration(client, siteUrl, period, options) {
+	return analyzePageConcentration(await fetchPages(client, siteUrl, period), options);
+}
+/**
+* Fetch keywords and analyze traffic concentration.
+* API calls: 1
+*/
+async function fetchKeywordConcentration(client, siteUrl, period, options) {
+	return analyzeKeywordConcentration(await fetchKeywords(client, siteUrl, period), options);
+}
+/**
+* Fetch keywords and analyze clusters.
+* API calls: 1
+*/
+async function fetchClustering(client, siteUrl, period, options) {
+	return analyzeClustering(await fetchKeywords(client, siteUrl, period), options);
+}
+/**
+* Fetch dates and analyze seasonality patterns.
+* API calls: 1
+*/
+async function fetchSeasonality(client, siteUrl, period, options) {
+	return analyzeSeasonality(await fetchDates(client, siteUrl, period), options);
+}
+/**
+* Fetch pages for both periods and analyze content decay.
+* API calls: 2
+*/
+async function fetchDecay(client, siteUrl, periods, options) {
+	const [current, previous] = await Promise.all([fetchPages(client, siteUrl, periods.current), fetchPages(client, siteUrl, periods.previous)]);
+	return analyzeDecay({
+		current,
+		previous
+	}, options);
+}
+/**
+* Fetch keywords for both periods and analyze movers/shakers.
+* API calls: 2
+*/
+async function fetchMovers(client, siteUrl, periods, options) {
+	const [current, previous] = await Promise.all([fetchKeywords(client, siteUrl, periods.current), fetchKeywords(client, siteUrl, periods.previous)]);
+	return analyzeMovers({
+		current,
+		previous
+	}, options);
+}
+
+//#endregion
+export { analyzeBrandSegmentation, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, createSorter, fetchBrandSegmentation, fetchClustering, fetchDecay, fetchKeywordConcentration, fetchMovers, fetchOpportunity, fetchPageConcentration, fetchSeasonality, fetchStrikingDistance, num, queryAnalytics, queryComparison };