gscdump 1.4.0 → 1.4.1

package/dist/query/index.mjs

@@ -1,234 +1,11 @@
-import { Countries, DATE_OPERATORS, Devices, SearchTypes, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, isQueryError, normalizeBuilderState, normalizeBuilderStateResult, normalizeFilter, queryErrorToException, queryErrors, resolveToBody, resolveToBodyResult } from "../_chunks/resolver.mjs";
-import { currentPstDate, daysAgoPst } from "../_chunks/dayjs.mjs";
+import { Countries, Devices, SearchTypes } from "./constants.mjs";
+import { UnresolvableDatasetError, UnsupportedLogicalCapabilityError, isQueryError, queryErrorToException, queryErrors } from "./errors.mjs";
+import { extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, normalizeBuilderState, normalizeBuilderStateResult, normalizeFilter, resolveToBody, resolveToBodyResult } from "./resolver.mjs";
+import { currentPstDate, daysAgoPst } from "./utils/dayjs.mjs";
+import { gsc } from "./builder.mjs";
+import { clicks, country, ctr, date, device, hour, impressions, page, position, query, queryCanonical, searchAppearance, searchType } from "./columns.mjs";
+import { and, between, contains, eq, gt, gte, inArray, like, lt, lte, ne, not, notRegex, or, regex, topLevel } from "./operators.mjs";
 import { buildLogicalComparisonPlan, buildLogicalComparisonPlanResult, buildLogicalPlan, buildLogicalPlanResult } from "./plan.mjs";
-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
-			});
-		},
-		prefilter(filter) {
-			return createBuilder({
-				...state,
-				prefilter: 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
-			});
-		},
-		dataState(s) {
-			return createBuilder({
-				...state,
-				dataState: s
-			});
-		},
-		aggregationType(t) {
-			return createBuilder({
-				...state,
-				aggregationType: t
-			});
-		},
-		type(t) {
-			return createBuilder({
-				...state,
-				searchType: t
-			});
-		},
-		toBody() {
-			return resolveToBody(state);
-		},
-		getState() {
-			return { ...state };
-		}
-	};
-}
-const gsc = createBuilder({ dimensions: [] });
-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 hour = createColumn("hour");
-const clicks = createMetricColumn("clicks");
-const impressions = createMetricColumn("impressions");
-const ctr = createMetricColumn("ctr");
-const position = createMetricColumn("position");
-const searchType = createQueryParam("searchType");
-function leafFilter(dimension, operator, expression, expression2) {
-	const filter = {
-		dimension,
-		operator,
-		expression
-	};
-	if (expression2 !== void 0) filter.expression2 = expression2;
-	return {
-		_constraints: {},
-		_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 leafFilter(column.dimension, "notEquals", String(value));
-}
-function inArray(column, values) {
-	if (values.length === 0) throw new Error(`inArray(${column.dimension}, []) requires at least one value`);
-	return {
-		_constraints: {},
-		_filters: values.map((v) => ({
-			dimension: column.dimension,
-			operator: "equals",
-			expression: String(v)
-		})),
-		_groupType: "or"
-	};
-}
-function contains(column, pattern) {
-	return leafFilter(column.dimension, "contains", pattern);
-}
-function like(column, pattern) {
-	if (!/[%_]/.test(pattern)) return leafFilter(column.dimension, "contains", pattern);
-	const regex = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/%/g, ".*").replace(/_/g, ".");
-	return leafFilter(column.dimension, "includingRegex", regex);
-}
-function regex(column, pattern) {
-	return leafFilter(column.dimension, "includingRegex", typeof pattern === "string" ? pattern : pattern.source);
-}
-function notRegex(column, pattern) {
-	return leafFilter(column.dimension, "excludingRegex", typeof pattern === "string" ? pattern : pattern.source);
-}
-function and(...filters) {
-	const flatFilters = [];
-	const nestedGroups = [];
-	for (const f of filters) if (f._groupType === "or") nestedGroups.push(f);
-	else {
-		flatFilters.push(...f._filters);
-		if (f._nestedGroups) nestedGroups.push(...f._nestedGroups);
-	}
-	return {
-		_constraints: {},
-		_filters: flatFilters,
-		_nestedGroups: nestedGroups.length > 0 ? nestedGroups : void 0,
-		_groupType: "and"
-	};
-}
-function or(...filters) {
-	for (const f of filters) {
-		if (f._groupType === "and" && f._filters.length > 1) throw new Error("or() cannot contain a multi-leaf AND group: GSC filter groups do not nest. Restructure as flat OR or split into multiple queries.");
-		if (f._nestedGroups && f._nestedGroups.length > 0) throw new Error("or() cannot contain nested filter groups: GSC filter groups do not nest.");
-		for (const leaf of f._filters) {
-			if (leaf.dimension === "date") throw new Error("or() cannot contain a date filter: GSC date range is a top-level AND-applied request field, not a filter. Apply the date range outside the or() group.");
-			if (leaf.dimension === "searchType") throw new Error("or() cannot contain a searchType filter: GSC search type is a top-level AND-applied request field. Use .type() outside the or() group.");
-		}
-	}
-	return {
-		_constraints: {},
-		_filters: filters.flatMap((f) => f._filters),
-		_groupType: "or"
-	};
-}
-const INVERSIONS = {
-	equals: "notEquals",
-	notEquals: "equals",
-	contains: "notContains",
-	notContains: "contains",
-	includingRegex: "excludingRegex",
-	excludingRegex: "includingRegex"
-};
-function invertOperator(op) {
-	return INVERSIONS[op];
-}
-function not(filter) {
-	if ((filter._nestedGroups?.length ?? 0) > 0 || filter._filters.length !== 1) throw new Error("not() can only invert a single leaf filter. GSC filter groups do not support compound negation.");
-	const inverted = [];
-	for (const f of filter._filters) {
-		if (DATE_OPERATORS.includes(f.operator)) throw new Error(`not() cannot invert date operator "${f.operator}": GSC has no negated date filter.`);
-		if (!(f.operator in INVERSIONS)) throw new Error(`not() cannot invert operator "${f.operator}".`);
-		inverted.push({
-			...f,
-			operator: invertOperator(f.operator)
-		});
-	}
-	return {
-		_constraints: {},
-		_filters: inverted
-	};
-}
-function gte(column, value) {
-	return metricOrDimFilter(column, "metricGte", "gte", String(value));
-}
-function gt(column, value) {
-	return metricOrDimFilter(column, "metricGt", "gt", String(value));
-}
-function lte(column, value) {
-	return metricOrDimFilter(column, "metricLte", "lte", String(value));
-}
-function lt(column, 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", "");
-}
 function today() {
 	return currentPstDate();
 }

package/dist/query/operator-meta.mjs

@@ -0,0 +1,41 @@
+const DATE_OPERATORS = [
+	"gte",
+	"gt",
+	"lte",
+	"lt",
+	"between"
+];
+const METRIC_OPERATORS = [
+	"metricGte",
+	"metricGt",
+	"metricLte",
+	"metricLt",
+	"metricBetween"
+];
+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";
+}
+export { DATE_OPERATORS, FILTER_METRICS, METRIC_OPERATORS, QUERY_PARAMS, SPECIAL_OPERATORS, isDateOperator, isMetric, isMetricOperator, isQueryParam, isRegexOperator, isSpecialOperator };

package/dist/query/operators.d.mts

@@ -0,0 +1,24 @@
+import { Column, Dimension, DimensionValueMap, Filter, MergeConstraints, Metric, MetricColumn, QueryParam, QueryParamName, QueryParamValueMap } from "./types.mjs";
+declare function eq<D extends Dimension, V extends DimensionValueMap[D]>(column: Column<D>, value: V): Filter<Record<D, V>>;
+declare function eq<P extends QueryParamName, V extends QueryParamValueMap[P]>(param: QueryParam<P>, value: V): Filter<Record<P, V>>;
+declare function ne<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
+declare function inArray<D extends Dimension, V extends DimensionValueMap[D]>(column: Column<D>, values: readonly V[]): Filter<Record<D, V>>;
+declare function contains<D extends Dimension>(column: Column<D>, pattern: string): Filter<object>;
+declare function like<D extends Dimension>(column: Column<D>, pattern: string): Filter<object>;
+declare function regex<D extends Dimension>(column: Column<D>, pattern: RegExp | string): Filter<object>;
+declare function notRegex<D extends Dimension>(column: Column<D>, pattern: RegExp | string): Filter<object>;
+declare function and<F extends Filter<any>[]>(...filters: F): Filter<MergeConstraints<F>>;
+declare function or<F extends Filter<any>[]>(...filters: F): Filter<object>;
+declare function not<F extends Filter<any>>(filter: F): Filter<object>;
+declare function gte<M extends Metric>(column: MetricColumn<M>, value: number): Filter<object>;
+declare function gte(column: Column<'date'>, value: string): Filter<object>;
+declare function gt<M extends Metric>(column: MetricColumn<M>, value: number): Filter<object>;
+declare function gt(column: Column<'date'>, value: string): Filter<object>;
+declare function lte<M extends Metric>(column: MetricColumn<M>, value: number): Filter<object>;
+declare function lte(column: Column<'date'>, value: string): Filter<object>;
+declare function lt<M extends Metric>(column: MetricColumn<M>, value: number): Filter<object>;
+declare function lt(column: Column<'date'>, value: string): Filter<object>;
+declare function between<M extends Metric>(column: MetricColumn<M>, start: number, end: number): Filter<object>;
+declare function between(column: Column<'date'>, start: string, end: string): Filter<object>;
+declare function topLevel(column: Column<'page'>): Filter<object>;
+export { and, between, contains, eq, gt, gte, inArray, like, lt, lte, ne, not, notRegex, or, regex, topLevel };

package/dist/query/operators.mjs

@@ -0,0 +1,124 @@
+import { DATE_OPERATORS } from "./operator-meta.mjs";
+function leafFilter(dimension, operator, expression, expression2) {
+	const filter = {
+		dimension,
+		operator,
+		expression
+	};
+	if (expression2 !== void 0) filter.expression2 = expression2;
+	return {
+		_constraints: {},
+		_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 leafFilter(column.dimension, "notEquals", String(value));
+}
+function inArray(column, values) {
+	if (values.length === 0) throw new Error(`inArray(${column.dimension}, []) requires at least one value`);
+	return {
+		_constraints: {},
+		_filters: values.map((v) => ({
+			dimension: column.dimension,
+			operator: "equals",
+			expression: String(v)
+		})),
+		_groupType: "or"
+	};
+}
+function contains(column, pattern) {
+	return leafFilter(column.dimension, "contains", pattern);
+}
+function like(column, pattern) {
+	if (!/[%_]/.test(pattern)) return leafFilter(column.dimension, "contains", pattern);
+	const regex = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/%/g, ".*").replace(/_/g, ".");
+	return leafFilter(column.dimension, "includingRegex", regex);
+}
+function regex(column, pattern) {
+	return leafFilter(column.dimension, "includingRegex", typeof pattern === "string" ? pattern : pattern.source);
+}
+function notRegex(column, pattern) {
+	return leafFilter(column.dimension, "excludingRegex", typeof pattern === "string" ? pattern : pattern.source);
+}
+function and(...filters) {
+	const flatFilters = [];
+	const nestedGroups = [];
+	for (const f of filters) if (f._groupType === "or") nestedGroups.push(f);
+	else {
+		flatFilters.push(...f._filters);
+		if (f._nestedGroups) nestedGroups.push(...f._nestedGroups);
+	}
+	return {
+		_constraints: {},
+		_filters: flatFilters,
+		_nestedGroups: nestedGroups.length > 0 ? nestedGroups : void 0,
+		_groupType: "and"
+	};
+}
+function or(...filters) {
+	for (const f of filters) {
+		if (f._groupType === "and" && f._filters.length > 1) throw new Error("or() cannot contain a multi-leaf AND group: GSC filter groups do not nest. Restructure as flat OR or split into multiple queries.");
+		if (f._nestedGroups && f._nestedGroups.length > 0) throw new Error("or() cannot contain nested filter groups: GSC filter groups do not nest.");
+		for (const leaf of f._filters) {
+			if (leaf.dimension === "date") throw new Error("or() cannot contain a date filter: GSC date range is a top-level AND-applied request field, not a filter. Apply the date range outside the or() group.");
+			if (leaf.dimension === "searchType") throw new Error("or() cannot contain a searchType filter: GSC search type is a top-level AND-applied request field. Use .type() outside the or() group.");
+		}
+	}
+	return {
+		_constraints: {},
+		_filters: filters.flatMap((f) => f._filters),
+		_groupType: "or"
+	};
+}
+const INVERSIONS = {
+	equals: "notEquals",
+	notEquals: "equals",
+	contains: "notContains",
+	notContains: "contains",
+	includingRegex: "excludingRegex",
+	excludingRegex: "includingRegex"
+};
+function invertOperator(op) {
+	return INVERSIONS[op];
+}
+function not(filter) {
+	if ((filter._nestedGroups?.length ?? 0) > 0 || filter._filters.length !== 1) throw new Error("not() can only invert a single leaf filter. GSC filter groups do not support compound negation.");
+	const inverted = [];
+	for (const f of filter._filters) {
+		if (DATE_OPERATORS.includes(f.operator)) throw new Error(`not() cannot invert date operator "${f.operator}": GSC has no negated date filter.`);
+		if (!(f.operator in INVERSIONS)) throw new Error(`not() cannot invert operator "${f.operator}".`);
+		inverted.push({
+			...f,
+			operator: invertOperator(f.operator)
+		});
+	}
+	return {
+		_constraints: {},
+		_filters: inverted
+	};
+}
+function gte(column, value) {
+	return metricOrDimFilter(column, "metricGte", "gte", String(value));
+}
+function gt(column, value) {
+	return metricOrDimFilter(column, "metricGt", "gt", String(value));
+}
+function lte(column, value) {
+	return metricOrDimFilter(column, "metricLte", "lte", String(value));
+}
+function lt(column, 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", "");
+}
+export { and, between, contains, eq, gt, gte, inArray, like, lt, lte, ne, not, notRegex, or, regex, topLevel };

package/dist/query/plan.d.mts

@@ -1,3 +1,93 @@
-import { TableName } from "../_chunks/contracts.mjs";
-import { ComparisonFilter, LogicalComparisonPlan, LogicalDataset, LogicalDimensionFilter, LogicalFilterGroup, LogicalFilterLeaf, LogicalFilterNode, LogicalMetricFilter, LogicalQueryPlan, PlannerCapabilities, QueryError, QueryErrorKind, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, buildLogicalComparisonPlan, buildLogicalComparisonPlanResult, buildLogicalPlan, buildLogicalPlanResult, inferDataset, isDatasetResolvable, isStateResolvable } from "../_chunks/plan.mjs";
+import { TableName } from "../contracts.mjs";
+import { Result } from "../core/result.mjs";
+import { BuilderState, Dimension, FilterOperator, Metric, MetricOperator, QueryParamName } from "./types.mjs";
+import { QueryError, QueryErrorKind, UnresolvableDatasetError, UnsupportedLogicalCapabilityError } from "./errors.mjs";
+type LogicalDataset = TableName;
+type ComparisonFilter = 'new' | 'lost' | 'improving' | 'declining';
+interface PlannerCapabilities {
+  regex?: boolean;
+  multiDataset?: boolean;
+  comparisonJoin?: boolean;
+  windowTotals?: boolean;
+}
+interface LogicalDimensionFilter {
+  dimension: Dimension;
+  operator: FilterOperator;
+  expression: string;
+  expression2?: string;
+}
+interface LogicalMetricFilter {
+  metric: Metric;
+  operator: MetricOperator;
+  expression: number;
+  expression2?: number;
+}
+interface LogicalFilterLeaf {
+  kind: 'leaf';
+  filter: LogicalDimensionFilter;
+}
+interface LogicalFilterGroup {
+  kind: 'group';
+  groupType: 'and' | 'or';
+  children: LogicalFilterNode[];
+}
+type LogicalFilterNode = LogicalFilterLeaf | LogicalFilterGroup;
+interface LogicalQueryPlan {
+  dataset: LogicalDataset;
+  dimensions: Dimension[];
+  groupByDimensions: Dimension[];
+  hasDate: boolean;
+  metrics: Metric[];
+  dateRange: {
+    startDate: string;
+    endDate: string;
+  };
+  dimensionFilters: LogicalDimensionFilter[];
+  dimensionFilterTree?: LogicalFilterNode;
+  metricFilters: LogicalMetricFilter[];
+  prefilters: LogicalMetricFilter[];
+  specialFilters: {
+    topLevel: boolean;
+  };
+  queryParams: Partial<Record<QueryParamName, string>>;
+  orderBy?: BuilderState['orderBy'];
+  rowLimit?: number;
+  startRow?: number;
+}
+interface LogicalComparisonPlan {
+  current: LogicalQueryPlan;
+  previous: LogicalQueryPlan;
+  comparisonFilter?: ComparisonFilter;
+}
+declare function inferDataset(dimensions: readonly Dimension[], filterDims?: readonly Dimension[]): LogicalDataset;
+/**
+ * True when every grouped + filtered dimension fits inside one stored dataset,
+ * i.e. the query is answerable from stored Parquet/D1 tables without a live
+ * GSC call. `inferDataset` always returns *some* dataset; this predicate is
+ * how callers tell a genuine match from one that will fail at column-resolve
+ * time.
+ */
+declare function isDatasetResolvable(dimensions: readonly Dimension[], filterDims?: readonly Dimension[]): boolean;
+/**
+ * `BuilderState`-level convenience for {@link isDatasetResolvable}: extracts
+ * the state's dimension filters (the same way `buildLogicalPlan` does) and
+ * checks them against the grouped dimensions. Lets routing code (e.g. the
+ * composite source) detect a cross-dimension query without rebuilding a plan.
+ */
+declare function isStateResolvable(state: BuilderState): boolean;
+/**
+ * Errors-as-values core: builds the logical plan or returns a typed `QueryError`
+ * for every modelled failure (missing date range, a regex filter on an engine
+ * without regex pushdown, a cross-dimension query with no stored home).
+ * `buildLogicalPlan` is the throwing wrapper for call sites that prefer exceptions.
+ */
+declare function buildLogicalPlanResult(state: BuilderState, capabilities?: PlannerCapabilities): Result<LogicalQueryPlan, QueryError>;
+declare function buildLogicalPlan(state: BuilderState, capabilities?: PlannerCapabilities): LogicalQueryPlan;
+/**
+ * Errors-as-values core for the comparison plan: returns a typed `QueryError`
+ * when the engine lacks the comparison-join or multi-dataset capability the
+ * paired queries need, or when either side fails to plan.
+ */
+declare function buildLogicalComparisonPlanResult(current: BuilderState, previous: BuilderState, capabilities?: PlannerCapabilities, comparisonFilter?: ComparisonFilter): Result<LogicalComparisonPlan, QueryError>;
+declare function buildLogicalComparisonPlan(current: BuilderState, previous: BuilderState, capabilities?: PlannerCapabilities, comparisonFilter?: ComparisonFilter): LogicalComparisonPlan;
 export { ComparisonFilter, LogicalComparisonPlan, LogicalDataset, LogicalDimensionFilter, LogicalFilterGroup, LogicalFilterLeaf, LogicalFilterNode, LogicalMetricFilter, LogicalQueryPlan, PlannerCapabilities, type QueryError, type QueryErrorKind, type TableName, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, buildLogicalComparisonPlan, buildLogicalComparisonPlanResult, buildLogicalPlan, buildLogicalPlanResult, inferDataset, isDatasetResolvable, isStateResolvable };

package/dist/query/plan.mjs

@@ -1,5 +1,7 @@
 import { err, ok, unwrapResult } from "../core/result.mjs";
-import { UnresolvableDatasetError, UnsupportedLogicalCapabilityError, extractDateRange, extractMetricFilters, extractSpecialOperatorFilters, isDateOperator, isMetric, isQueryParam, isRegexOperator, normalizeFilter, queryErrorToException, queryErrors } from "../_chunks/resolver.mjs";
+import { UnresolvableDatasetError, UnsupportedLogicalCapabilityError, queryErrorToException, queryErrors } from "./errors.mjs";
+import { isDateOperator, isMetric, isQueryParam, isRegexOperator } from "./operator-meta.mjs";
+import { extractDateRange, extractMetricFilters, extractSpecialOperatorFilters, normalizeFilter } from "./resolver.mjs";
 function collectInternalFilters(filter) {
 	if (!filter || !("_filters" in filter)) return [];
 	const flat = filter._filters;

package/dist/query/resolver.d.mts

@@ -0,0 +1,40 @@
+import { GscSearchAnalyticsRequest } from "../contracts.mjs";
+import { Result } from "../core/result.mjs";
+import { SearchType } from "./constants.mjs";
+import { BuilderState, Filter, FilterInput, InternalFilter } from "./types.mjs";
+import { QueryError } from "./errors.mjs";
+declare function normalizeFilter(input?: FilterInput): Filter<any> | undefined;
+/**
+ * Errors-as-values core for {@link normalizeBuilderState}: returns an
+ * `invalid-builder-state` `QueryError` when the untrusted partner-API body is
+ * not an object, and an `invalid-filter` `QueryError` when a filter leaf lacks
+ * its string `dimension`/`operator`, instead of throwing. Also coerces
+ * alternative `orderBy` shapes into the canonical `{ column, dir }`.
+ * Receive-edge parse (parse, don't validate), so hosts can map a bad body to a
+ * 4xx and downstream consumers only ever see the canonical shape.
+ */
+declare function normalizeBuilderStateResult(state: unknown): Result<BuilderState, QueryError>;
+declare function normalizeBuilderState(state: unknown): BuilderState;
+declare function extractDateRange(input?: FilterInput): {
+  startDate?: string;
+  endDate?: string;
+};
+declare function extractMetricFilters(input?: FilterInput): InternalFilter[];
+declare function extractSpecialOperatorFilters(input?: FilterInput): InternalFilter[];
+/**
+ * Pull `searchType` out of a BuilderState filter. Returns undefined for
+ * missing/invalid shapes — callers treat that as "no scope" (cross-type read).
+ * Validated against the canonical `SearchTypes` set so unknown strings
+ * don't reach the engine.
+ */
+declare function extractSearchType(state: BuilderState | undefined | null): SearchType | undefined;
+/**
+ * Errors-as-values core: turns a `BuilderState` into a GSC API request body or
+ * returns a typed `QueryError` for every modelled bad-query case (missing date
+ * range, out-of-range row limit / start row, hour/dataState mismatch, illegal
+ * aggregationType combination). `resolveToBody` is the throwing wrapper over this
+ * for `.toBody()` and the live-API client paths.
+ */
+declare function resolveToBodyResult(state: BuilderState): Result<GscSearchAnalyticsRequest, QueryError>;
+declare function resolveToBody(state: BuilderState): GscSearchAnalyticsRequest;
+export { extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, normalizeBuilderState, normalizeBuilderStateResult, normalizeFilter, resolveToBody, resolveToBodyResult };