gscdump 0.4.0 → 0.6.0

package/dist/query/index.mjs

@@ -1,12 +1,10 @@
 import _dayjs from "dayjs";
 import timezone from "dayjs/plugin/timezone.js";
 import utc from "dayjs/plugin/utc.js";
-
-//#region src/query/utils/dayjs.ts
 _dayjs.extend(utc);
 _dayjs.extend(timezone);
-function dayjs(date$1) {
-	return _dayjs(date$1);
+function dayjs(date) {
+	return _dayjs(date);
 }
 function currentPstDate() {
 	return dayjs().tz("America/Los_Angeles").hour(12).minute(0).second(0).format("YYYY-MM-DD");
@@ -14,9 +12,13 @@ function currentPstDate() {
 function dayjsPst() {
 	return dayjs().tz("America/Los_Angeles").hour(12).minute(0).second(0);
 }
-
-//#endregion
-//#region src/query/resolver.ts
+const MS_PER_DAY = 864e5;
+function toIsoDate(d) {
+	return d.toISOString().slice(0, 10);
+}
+function addDays(dateStr, n) {
+	return toIsoDate(new Date(Date.parse(`${dateStr}T00:00:00Z`) + n * MS_PER_DAY));
+}
 const DATE_OPERATORS = [
 	"gte",
 	"gt",
@@ -33,6 +35,30 @@ const METRIC_OPERATORS = [
 ];
 const SPECIAL_OPERATORS = ["topLevel"];
 const QUERY_PARAMS = ["searchType"];
+const FILTER_METRICS = [
+	"clicks",
+	"impressions",
+	"ctr",
+	"position"
+];
+function isDateOperator(op) {
+	return DATE_OPERATORS.includes(op);
+}
+function isMetricOperator(op) {
+	return METRIC_OPERATORS.includes(op);
+}
+function isSpecialOperator(op) {
+	return SPECIAL_OPERATORS.includes(op);
+}
+function isQueryParam(value) {
+	return QUERY_PARAMS.includes(value);
+}
+function isMetric(value) {
+	return FILTER_METRICS.includes(value);
+}
+function isRegexOperator(op) {
+	return op === "includingRegex" || op === "excludingRegex";
+}
 function isJsonFilter(value) {
 	return typeof value === "object" && value !== null && "_filters" in value && Array.isArray(value._filters);
 }
@@ -49,32 +75,56 @@ function parseJsonFilter(json) {
 		_groupType: json._groupType
 	};
 }
-function normalizeFilter(input) {
-	if (!input) return void 0;
-	return input;
+function isWireGroupType(type) {
+	return type === "and" || type === "or";
 }
-function isMetricOperator(op) {
-	return METRIC_OPERATORS.includes(op);
-}
-function isSpecialOperator(op) {
-	return SPECIAL_OPERATORS.includes(op);
+function convertWireLeaf(alt) {
+	if (!alt.column || !alt.type || isWireGroupType(alt.type)) return null;
+	const f = {
+		dimension: alt.column,
+		operator: alt.type,
+		expression: alt.type === "between" ? alt.from ?? "" : alt.value ?? ""
+	};
+	if (alt.type === "between" && alt.to) f.expression2 = alt.to;
+	return f;
 }
-function isDateOperator(op) {
-	return DATE_OPERATORS.includes(op);
+function convertWireGroup(alt) {
+	if (!isWireGroupType(alt.type)) {
+		const leaf = convertWireLeaf(alt);
+		return leaf ? { _filters: [leaf] } : null;
+	}
+	const leaves = [];
+	const nested = [];
+	for (const child of alt.filters ?? []) if (isWireGroupType(child.type)) {
+		const sub = convertWireGroup(child);
+		if (sub) nested.push(sub);
+	} else {
+		const leaf = convertWireLeaf(child);
+		if (leaf) leaves.push(leaf);
+	}
+	if (leaves.length === 0 && nested.length === 0) return null;
+	return {
+		_filters: leaves,
+		_nestedGroups: nested.length > 0 ? nested : void 0,
+		_groupType: alt.type
+	};
 }
-function isQueryParam(dim) {
-	return QUERY_PARAMS.includes(dim);
+function isWireFilter(input) {
+	if (!input || typeof input !== "object") return false;
+	const o = input;
+	if ("_filters" in o) return false;
+	return "type" in o && typeof o.type === "string" || "filters" in o && Array.isArray(o.filters);
 }
-function addDays(dateStr, days) {
-	const d = new Date(dateStr);
-	d.setDate(d.getDate() + days);
-	return d.toISOString().split("T")[0];
+function normalizeFilter(input) {
+	if (!input) return void 0;
+	if (isWireFilter(input)) return convertWireGroup(input) ?? void 0;
+	return input;
 }
 function extractSpecialFilters(filter) {
 	if (!filter) return {};
 	let startDate;
 	let endDate;
-	let searchType$1;
+	let searchType;
 	const otherFilters = [];
 	const cleanedNestedGroups = [];
 	for (const f of filter._filters) if (f.dimension === "date" && isDateOperator(f.operator)) switch (f.operator) {
@@ -96,14 +146,14 @@ function extractSpecialFilters(filter) {
 			break;
 	}
 	else if (isQueryParam(f.dimension)) {
-		if (f.dimension === "searchType") searchType$1 = f.expression;
+		if (f.dimension === "searchType") searchType = 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.searchType) searchType = extracted.searchType;
 		if (extracted.dimensionFilter) cleanedNestedGroups.push(extracted.dimensionFilter);
 	}
 	const dimensionFilter = otherFilters.length > 0 || cleanedNestedGroups.length > 0 ? {
@@ -114,7 +164,7 @@ function extractSpecialFilters(filter) {
 	return {
 		startDate,
 		endDate,
-		searchType: searchType$1,
+		searchType,
 		dimensionFilter
 	};
 }
@@ -140,14 +190,14 @@ function extractSpecialOperatorFilters(input) {
 	return [...special, ...nested];
 }
 function resolveToBody(state) {
-	const { startDate, endDate, searchType: searchType$1, dimensionFilter } = extractSpecialFilters(state.filter);
+	const { startDate, endDate, searchType, 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 (searchType) body.searchType = searchType;
 	if (state.rowLimit) body.rowLimit = state.rowLimit;
 	if (state.startRow) body.startRow = state.startRow;
 	const filterGroups = resolveFilter(dimensionFilter);
@@ -179,9 +229,6 @@ function resolveFilter(filter) {
 	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";
 }
@@ -242,9 +289,6 @@ function createBuilder(state) {
 	};
 }
 const gsc = createBuilder({ dimensions: [] });
-
-//#endregion
-//#region src/query/columns.ts
 function createColumn(dimension) {
 	return { dimension };
 }
@@ -266,9 +310,6 @@ const impressions = createMetricColumn("impressions");
 const ctr = createMetricColumn("ctr");
 const position = createMetricColumn("position");
 const searchType = createQueryParam("searchType");
-
-//#endregion
-//#region src/query/utils/countries.ts
 var countries_default = [
 	{
 		"name": "Afghanistan",
@@ -1765,9 +1806,6 @@ var countries_default = [
 		"country-code": "716"
 	}
 ];
-
-//#endregion
-//#region src/query/constants.ts
 const Devices = {
 	MOBILE: "MOBILE",
 	DESKTOP: "DESKTOP",
@@ -1777,31 +1815,31 @@ const SearchTypes = {
 	WEB: "web",
 	IMAGE: "image",
 	VIDEO: "video",
-	NEWS: "news"
+	NEWS: "news",
+	DISCOVER: "discover",
+	GOOGLE_NEWS: "googleNews"
 };
 const Countries = Object.fromEntries(countries_default.map((c) => [c["alpha-3"], c["alpha-3"].toLowerCase()]));
-
-//#endregion
-//#region src/query/operators.ts
-function eq(columnOrParam, value) {
+function leafFilter(dimension, operator, expression, expression2) {
+	const filter = {
+		dimension,
+		operator,
+		expression
+	};
+	if (expression2 !== void 0) filter.expression2 = expression2;
 	return {
 		_constraints: {},
-		_filters: [{
-			dimension: "dimension" in columnOrParam ? columnOrParam.dimension : columnOrParam.param,
-			operator: "equals",
-			expression: String(value)
-		}]
+		_filters: [filter]
 	};
 }
+function metricOrDimFilter(column, metricOp, dimOp, expression, expression2) {
+	return "metric" in column ? leafFilter(column.metric, metricOp, expression, expression2) : leafFilter(column.dimension, dimOp, expression, expression2);
+}
+function eq(columnOrParam, value) {
+	return leafFilter("dimension" in columnOrParam ? columnOrParam.dimension : columnOrParam.param, "equals", String(value));
+}
 function ne(column, value) {
-	return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.dimension,
-			operator: "notEquals",
-			expression: String(value)
-		}]
-	};
+	return leafFilter(column.dimension, "notEquals", String(value));
 }
 function inArray(column, values) {
 	return {
@@ -1815,44 +1853,16 @@ function inArray(column, values) {
 	};
 }
 function contains(column, pattern) {
-	return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.dimension,
-			operator: "contains",
-			expression: pattern
-		}]
-	};
+	return leafFilter(column.dimension, "contains", pattern);
 }
 function like(column, pattern) {
-	return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.dimension,
-			operator: "contains",
-			expression: pattern.replace(/%/g, "")
-		}]
-	};
+	return leafFilter(column.dimension, "contains", pattern.replace(/%/g, ""));
 }
 function regex(column, pattern) {
-	return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.dimension,
-			operator: "includingRegex",
-			expression: typeof pattern === "string" ? pattern : pattern.source
-		}]
-	};
+	return leafFilter(column.dimension, "includingRegex", typeof pattern === "string" ? pattern : pattern.source);
 }
 function notRegex(column, pattern) {
-	return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.dimension,
-			operator: "excludingRegex",
-			expression: typeof pattern === "string" ? pattern : pattern.source
-		}]
-	};
+	return leafFilter(column.dimension, "excludingRegex", typeof pattern === "string" ? pattern : pattern.source);
 }
 function and(...filters) {
 	const flatFilters = [];
@@ -1876,17 +1886,10 @@ function or(...filters) {
 		_groupType: "or"
 	};
 }
-const DATE_OPS = [
-	"gte",
-	"gt",
-	"lte",
-	"lt",
-	"between"
-];
 function not(filter) {
 	return {
 		_constraints: {},
-		_filters: filter._filters.filter((f) => !DATE_OPS.includes(f.operator)).map((f) => ({
+		_filters: filter._filters.filter((f) => !DATE_OPERATORS.includes(f.operator)).map((f) => ({
 			...f,
 			operator: invertOperator(f.operator)
 		}))
@@ -1903,116 +1906,161 @@ function invertOperator(op) {
 	}[op];
 }
 function gte(column, value) {
-	if ("metric" in column) return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.metric,
-			operator: "metricGte",
-			expression: String(value)
-		}]
-	};
-	return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.dimension,
-			operator: "gte",
-			expression: String(value)
-		}]
-	};
+	return metricOrDimFilter(column, "metricGte", "gte", String(value));
 }
 function gt(column, value) {
-	if ("metric" in column) return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.metric,
-			operator: "metricGt",
-			expression: String(value)
-		}]
-	};
-	return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.dimension,
-			operator: "gt",
-			expression: String(value)
-		}]
-	};
+	return metricOrDimFilter(column, "metricGt", "gt", String(value));
 }
 function lte(column, value) {
-	if ("metric" in column) return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.metric,
-			operator: "metricLte",
-			expression: String(value)
-		}]
-	};
-	return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.dimension,
-			operator: "lte",
-			expression: String(value)
-		}]
-	};
+	return metricOrDimFilter(column, "metricLte", "lte", String(value));
 }
 function lt(column, value) {
-	if ("metric" in column) return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.metric,
-			operator: "metricLt",
-			expression: String(value)
-		}]
-	};
+	return metricOrDimFilter(column, "metricLt", "lt", String(value));
+}
+function between(column, start, end) {
+	return metricOrDimFilter(column, "metricBetween", "between", String(start), String(end));
+}
+function topLevel(column) {
+	return leafFilter(column.dimension, "topLevel", "");
+}
+var UnsupportedLogicalCapabilityError = class extends Error {
+	constructor(capability, context) {
+		super(`${context} requires ${capability} capability`);
+		this.name = "UnsupportedLogicalCapabilityError";
+	}
+};
+function collectInternalFilters(filter) {
+	if (!filter || !("_filters" in filter)) return [];
+	const flat = filter._filters;
+	const nested = filter._nestedGroups?.flatMap((group) => collectInternalFilters(group)) ?? [];
+	return [...flat, ...nested];
+}
+function inferDataset(dimensions, filterDims = []) {
+	const allDims = new Set([...dimensions, ...filterDims]);
+	const has = (dimension) => allDims.has(dimension);
+	if (has("searchAppearance")) return "search_appearance";
+	if (has("page") && (has("query") || has("queryCanonical"))) return "page_keywords";
+	if (has("query") || has("queryCanonical")) return "keywords";
+	if (has("page")) return "pages";
+	if (has("country")) return "countries";
+	if (has("device")) return "devices";
+	return "keywords";
+}
+function requireCapability(capabilities, capability, enabled, context) {
+	if (enabled && !capabilities?.[capability]) throw new UnsupportedLogicalCapabilityError(capability, context);
+}
+function isDimensionLeaf(filter) {
+	if (isMetric(filter.dimension)) return false;
+	if (filter.dimension === "date" && isDateOperator(filter.operator)) return false;
+	if (filter.operator === "topLevel" || filter.operator.startsWith("metric")) return false;
+	if (isQueryParam(filter.dimension)) return false;
+	return true;
+}
+function toLogicalDimensionFilter(filter) {
 	return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.dimension,
-			operator: "lt",
-			expression: String(value)
-		}]
+		dimension: filter.dimension,
+		operator: filter.operator,
+		expression: filter.expression,
+		expression2: filter.expression2
 	};
 }
-function between(column, start, end) {
-	if ("metric" in column) return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.metric,
-			operator: "metricBetween",
-			expression: String(start),
-			expression2: String(end)
-		}]
+function buildDimensionFilterTree(filter, capabilities) {
+	if (!filter || !("_filters" in filter)) return void 0;
+	const groupType = filter._groupType ?? "and";
+	const children = [];
+	for (const f of filter._filters) {
+		if (!isDimensionLeaf(f)) continue;
+		requireCapability(capabilities, "regex", isRegexOperator(f.operator), "logical plan");
+		children.push({
+			kind: "leaf",
+			filter: toLogicalDimensionFilter(f)
+		});
+	}
+	for (const g of filter._nestedGroups ?? []) {
+		const sub = buildDimensionFilterTree(g, capabilities);
+		if (sub) children.push(sub);
+	}
+	if (children.length === 0) return void 0;
+	if (children.length === 1) return children[0];
+	return {
+		kind: "group",
+		groupType,
+		children
 	};
+}
+function buildLogicalPlan(state, capabilities = {}) {
+	const normalizedFilter = normalizeFilter(state.filter);
+	const { startDate, endDate } = extractDateRange(normalizedFilter);
+	if (!startDate || !endDate) throw new Error("logical plan requires date range (use between(date, ...) or gte/lte)");
+	const allFilters = collectInternalFilters(normalizedFilter);
+	const metricFilters = extractMetricFilters(normalizedFilter);
+	const specialFilters = extractSpecialOperatorFilters(normalizedFilter);
+	const queryParams = {};
+	const dimensionFilters = [];
+	for (const filter of allFilters) {
+		if (isMetric(filter.dimension)) continue;
+		if (filter.dimension === "date" && isDateOperator(filter.operator)) continue;
+		if (filter.operator === "topLevel" || filter.operator.startsWith("metric")) continue;
+		if (isQueryParam(filter.dimension)) {
+			queryParams[filter.dimension] = filter.expression;
+			continue;
+		}
+		const operator = filter.operator;
+		requireCapability(capabilities, "regex", isRegexOperator(operator), "logical plan");
+		dimensionFilters.push({
+			dimension: filter.dimension,
+			operator,
+			expression: filter.expression,
+			expression2: filter.expression2
+		});
+	}
+	const dimensionFilterTree = buildDimensionFilterTree(normalizedFilter, capabilities);
+	const filterDims = dimensionFilters.map((filter) => filter.dimension);
 	return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.dimension,
-			operator: "between",
-			expression: String(start),
-			expression2: String(end)
-		}]
+		dataset: inferDataset(state.dimensions, filterDims),
+		dimensions: [...state.dimensions],
+		groupByDimensions: state.dimensions.filter((d) => d !== "date"),
+		hasDate: state.dimensions.includes("date"),
+		metrics: state.metrics ? [...state.metrics] : [
+			"clicks",
+			"impressions",
+			"ctr",
+			"position"
+		],
+		dateRange: {
+			startDate,
+			endDate
+		},
+		dimensionFilters,
+		dimensionFilterTree,
+		metricFilters: metricFilters.map((filter) => ({
+			metric: filter.dimension,
+			operator: filter.operator,
+			expression: Number(filter.expression),
+			expression2: filter.expression2 == null ? void 0 : Number(filter.expression2)
+		})),
+		specialFilters: { topLevel: specialFilters.some((filter) => filter.operator === "topLevel") },
+		queryParams,
+		orderBy: state.orderBy,
+		rowLimit: state.rowLimit,
+		startRow: state.startRow
 	};
 }
-function topLevel(column) {
+function buildLogicalComparisonPlan(current, previous, capabilities = {}, comparisonFilter) {
+	requireCapability(capabilities, "comparisonJoin", true, "logical comparison plan");
+	const currentPlan = buildLogicalPlan(current, capabilities);
+	const previousPlan = buildLogicalPlan(previous, capabilities);
+	requireCapability(capabilities, "multiDataset", currentPlan.dataset !== previousPlan.dataset, "logical comparison plan");
 	return {
-		_constraints: {},
-		_filters: [{
-			dimension: column.dimension,
-			operator: "topLevel",
-			expression: ""
-		}]
+		current: currentPlan,
+		previous: previousPlan,
+		comparisonFilter
 	};
 }
-
-//#endregion
-//#region src/query/index.ts
 function today() {
 	return currentPstDate();
 }
 function daysAgo(n) {
 	return dayjsPst().subtract(n, "day").format("YYYY-MM-DD");
 }
-
-//#endregion
-export { Countries, Devices, SearchTypes, and, between, clicks, contains, country, ctr, currentPstDate, date, dayjs, dayjsPst, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSpecialOperatorFilters, gsc, gt, gte, impressions, inArray, isJsonFilter, like, lt, lte, ne, not, notRegex, or, page, parseJsonFilter, position, query, queryCanonical, regex, searchAppearance, searchType, today, topLevel };
+export { Countries, Devices, SearchTypes, UnsupportedLogicalCapabilityError, and, between, buildLogicalComparisonPlan, buildLogicalPlan, clicks, contains, country, ctr, currentPstDate, date, dayjs, dayjsPst, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSpecialOperatorFilters, gsc, gt, gte, impressions, inArray, isJsonFilter, like, lt, lte, ne, normalizeFilter, not, notRegex, or, page, parseJsonFilter, position, query, queryCanonical, regex, searchAppearance, searchType, today, topLevel };