gscdump 0.25.14 → 0.26.0

package/dist/query/index.d.mts

@@ -169,6 +169,87 @@ declare const impressions: MetricColumn<"impressions">;
 declare const ctr: MetricColumn<"ctr">;
 declare const position: MetricColumn<"position">;
 declare const searchType: QueryParam<"searchType">;
+type QueryErrorKind = 'missing-date-range' | 'invalid-row-limit' | 'invalid-start-row' | 'invalid-data-state' | 'invalid-aggregation-type' | 'invalid-builder-state' | 'unsupported-capability' | 'unresolvable-dataset';
+type QueryError = {
+  kind: 'missing-date-range';
+  message: string;
+} | {
+  kind: 'invalid-row-limit';
+  value: unknown;
+  message: string;
+} | {
+  kind: 'invalid-start-row';
+  value: unknown;
+  message: string;
+} | {
+  kind: 'invalid-data-state';
+  message: string;
+} | {
+  kind: 'invalid-aggregation-type';
+  message: string;
+} | {
+  kind: 'invalid-builder-state';
+  message: string;
+  cause?: unknown;
+} | {
+  kind: 'unsupported-capability';
+  capability: string;
+  context: string;
+  message: string;
+} | {
+  kind: 'unresolvable-dataset';
+  dimensions: readonly Dimension[];
+  filterDims: readonly Dimension[];
+  message: string;
+};
+declare const queryErrors: {
+  readonly missingDateRange: () => QueryError;
+  readonly invalidRowLimit: (value: unknown) => QueryError;
+  readonly invalidStartRow: (value: unknown) => QueryError;
+  readonly hourDimensionRequiresHourlyState: () => QueryError;
+  readonly hourlyStateRequiresHourDimension: () => QueryError;
+  readonly byPropertyUnsupportedSearchType: () => QueryError;
+  readonly byPropertyNotAllowedWithPage: () => QueryError;
+  readonly byNewsShowcaseRequiresSearchType: () => QueryError;
+  readonly byNewsShowcaseNotAllowedWithPage: () => QueryError;
+  readonly byNewsShowcaseRequiresShowcaseFilter: () => QueryError;
+  readonly invalidBuilderState: (cause?: unknown) => QueryError;
+  readonly unsupportedCapability: (capability: string, context: string) => QueryError;
+  readonly unresolvableDataset: (dimensions: readonly Dimension[], filterDims?: readonly Dimension[]) => QueryError;
+};
+declare function isQueryError(value: unknown): value is QueryError;
+/** The human-readable rendering of a `QueryError`, for logs and string sinks. */
+declare function formatQueryError(error: QueryError): string;
+/**
+ * Thrown when a query needs a planner capability (regex pushdown, comparison
+ * joins, multi-dataset reads) the target engine lacks. Engines catch it to fall
+ * back to the live GSC API. Carries the typed `queryError` value so a caller can
+ * read the modelled failure instead of parsing the message.
+ */
+declare class UnsupportedLogicalCapabilityError extends Error {
+  readonly queryError: Extract<QueryError, {
+    kind: 'unsupported-capability';
+  }>;
+  constructor(capability: string, context: string);
+}
+/**
+ * Thrown when a query's grouped + filtered dimensions span more than one stored
+ * dataset. Replaces the resolver's raw "unknown column" error so hosts can map
+ * it to a 4xx instead of leaking an opaque 500. Carries the typed `queryError`.
+ */
+declare class UnresolvableDatasetError extends Error {
+  readonly queryError: Extract<QueryError, {
+    kind: 'unresolvable-dataset';
+  }>;
+  constructor(dimensions: readonly Dimension[], filterDims?: readonly Dimension[]);
+}
+/**
+ * Re-raises a `QueryError` value as an `Error`, preserving the historical class
+ * identity for the two errors engines match on by name (`UnresolvableDatasetError`,
+ * `UnsupportedLogicalCapabilityError`). Pairs with `unwrapResult` so a
+ * `fooResult(): Result<A, QueryError>` core can back a throwing `foo()`.
+ */
+declare function queryErrorToException(error: QueryError): Error;
 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>;
@@ -191,6 +272,15 @@ 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>;
+interface Ok<A> {
+  readonly ok: true;
+  readonly value: A;
+}
+interface Err<E> {
+  readonly ok: false;
+  readonly error: E;
+}
+type Result<A, E> = Ok<A> | Err<E>;
 type LogicalDataset = TableName;
 type ComparisonFilter = 'new' | 'lost' | 'improving' | 'declining';
 interface PlannerCapabilities {
@@ -248,14 +338,31 @@ interface LogicalComparisonPlan {
   previous: LogicalQueryPlan;
   comparisonFilter?: ComparisonFilter;
 }
-declare class UnsupportedLogicalCapabilityError extends Error {
-  constructor(capability: keyof PlannerCapabilities, context: string);
-}
+/**
+ * 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;
 declare function isJsonFilter(value: unknown): value is JsonFilter;
 declare function parseJsonFilter(json: JsonFilter): Filter<any>;
 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, instead of throwing. Receive-edge parse, so hosts can map a bad
+ * body to a 4xx.
+ */
+declare function normalizeBuilderStateResult(state: unknown): Result<BuilderState, QueryError>;
 declare function normalizeBuilderState(state: unknown): BuilderState;
 declare function extractDateRange(input?: FilterInput): {
   startDate?: string;
@@ -270,7 +377,16 @@ declare function extractSpecialOperatorFilters(input?: FilterInput): InternalFil
  * 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;
 declare function currentPstDate(): string;
 declare function today(): string;
 declare function daysAgo(n: number): string;
-export { type BuilderState, type Column, type ComparisonFilter, Countries, type Country, type Device, Devices, type Dimension, type DimensionValueMap, type Filter, type FilterInput, type GSCQueryBuilder, type GSCResult, type GSCRow, type InternalFilter, type JsonFilter, type JsonInternalFilter, type LogicalComparisonPlan, type LogicalDataset, type LogicalDimensionFilter, type LogicalMetricFilter, type LogicalQueryPlan, type Metric, type MetricColumn, type PlannerCapabilities, type QueryParam, type QueryParamName, type QueryParamValueMap, type SearchType, SearchTypes, UnsupportedLogicalCapabilityError, and, between, buildLogicalComparisonPlan, buildLogicalPlan, clicks, contains, country, ctr, currentPstDate, date, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, gsc, gt, gte, hour, impressions, inArray, isJsonFilter, like, lt, lte, ne, normalizeBuilderState, normalizeFilter, not, notRegex, or, page, parseJsonFilter, position, query, queryCanonical, regex, searchAppearance, searchType, today, topLevel };
+export { type BuilderState, type Column, type ComparisonFilter, Countries, type Country, type Device, Devices, type Dimension, type DimensionValueMap, type Filter, type FilterInput, type GSCQueryBuilder, type GSCResult, type GSCRow, type InternalFilter, type JsonFilter, type JsonInternalFilter, type LogicalComparisonPlan, type LogicalDataset, type LogicalDimensionFilter, type LogicalMetricFilter, type LogicalQueryPlan, type Metric, type MetricColumn, type PlannerCapabilities, QueryError, QueryErrorKind, type QueryParam, type QueryParamName, type QueryParamValueMap, type SearchType, SearchTypes, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, and, between, buildLogicalComparisonPlan, buildLogicalComparisonPlanResult, buildLogicalPlan, buildLogicalPlanResult, clicks, contains, country, ctr, currentPstDate, date, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, formatQueryError, gsc, gt, gte, hour, impressions, inArray, isJsonFilter, isQueryError, like, lt, lte, ne, normalizeBuilderState, normalizeBuilderStateResult, normalizeFilter, not, notRegex, or, page, parseJsonFilter, position, query, queryCanonical, queryErrorToException, queryErrors, regex, resolveToBody, resolveToBodyResult, searchAppearance, searchType, today, topLevel };

package/dist/query/index.mjs

@@ -29,6 +29,22 @@ function toIsoDate(d) {
 function addDays(dateStr, n) {
 	return toIsoDate(new Date(Date.parse(`${dateStr}T00:00:00Z`) + n * MS_PER_DAY));
 }
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function err(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+function unwrapResult(result, toError) {
+	if (result.ok) return result.value;
+	throw toError(result.error);
+}
 var countries_default = [
 	{
 		"name": "Afghanistan",
@@ -1539,6 +1555,142 @@ const SearchTypes = {
 	GOOGLE_NEWS: "googleNews"
 };
 const Countries = Object.fromEntries(countries_default.map((c) => [c["alpha-3"], c["alpha-3"].toLowerCase()]));
+const TIME_AXIS_DIMENSIONS$1 = new Set(["date", "hour"]);
+const queryErrors = {
+	missingDateRange() {
+		return {
+			kind: "missing-date-range",
+			message: "Date range required: use .where(between(date, start, end)) or .where(and(gte(date, start), lte(date, end)))"
+		};
+	},
+	invalidRowLimit(value) {
+		return {
+			kind: "invalid-row-limit",
+			value,
+			message: `rowLimit must be a positive integer, got ${value}`
+		};
+	},
+	invalidStartRow(value) {
+		return {
+			kind: "invalid-start-row",
+			value,
+			message: `startRow must be a non-negative integer, got ${value}`
+		};
+	},
+	hourDimensionRequiresHourlyState() {
+		return {
+			kind: "invalid-data-state",
+			message: "hour dimension requires dataState: \"hourly_all\""
+		};
+	},
+	hourlyStateRequiresHourDimension() {
+		return {
+			kind: "invalid-data-state",
+			message: "dataState: \"hourly_all\" requires grouping by hour dimension"
+		};
+	},
+	byPropertyUnsupportedSearchType() {
+		return {
+			kind: "invalid-aggregation-type",
+			message: "aggregationType: \"byProperty\" is not supported for type \"discover\" or \"googleNews\""
+		};
+	},
+	byPropertyNotAllowedWithPage() {
+		return {
+			kind: "invalid-aggregation-type",
+			message: "aggregationType: \"byProperty\" is not allowed when grouping or filtering by page"
+		};
+	},
+	byNewsShowcaseRequiresSearchType() {
+		return {
+			kind: "invalid-aggregation-type",
+			message: "aggregationType: \"byNewsShowcasePanel\" requires type \"discover\" or \"googleNews\""
+		};
+	},
+	byNewsShowcaseNotAllowedWithPage() {
+		return {
+			kind: "invalid-aggregation-type",
+			message: "aggregationType: \"byNewsShowcasePanel\" is not allowed when grouping or filtering by page"
+		};
+	},
+	byNewsShowcaseRequiresShowcaseFilter() {
+		return {
+			kind: "invalid-aggregation-type",
+			message: "aggregationType: \"byNewsShowcasePanel\" requires a searchAppearance equals \"NEWS_SHOWCASE\" filter and no other searchAppearance filter"
+		};
+	},
+	invalidBuilderState(cause) {
+		return {
+			kind: "invalid-builder-state",
+			cause,
+			message: "Invalid state"
+		};
+	},
+	unsupportedCapability(capability, context) {
+		return {
+			kind: "unsupported-capability",
+			capability,
+			context,
+			message: `${context} requires ${capability} capability`
+		};
+	},
+	unresolvableDataset(dimensions, filterDims = []) {
+		const grouped = dimensions.filter((d) => !TIME_AXIS_DIMENSIONS$1.has(d));
+		const filtered = filterDims.filter((d) => !TIME_AXIS_DIMENSIONS$1.has(d));
+		return {
+			kind: "unresolvable-dataset",
+			dimensions,
+			filterDims,
+			message: `Cannot resolve a [${grouped.join(", ")}] breakdown filtered by [${filtered.join(", ")}] from stored data: these dimensions live in separate per-dimension tables. Only the live GSC API computes cross-dimension aggregates.`
+		};
+	}
+};
+const QUERY_ERROR_KINDS = new Set([
+	"missing-date-range",
+	"invalid-row-limit",
+	"invalid-start-row",
+	"invalid-data-state",
+	"invalid-aggregation-type",
+	"invalid-builder-state",
+	"unsupported-capability",
+	"unresolvable-dataset"
+]);
+function isQueryError(value) {
+	return typeof value === "object" && value !== null && QUERY_ERROR_KINDS.has(value.kind) && typeof value.message === "string";
+}
+function formatQueryError(error) {
+	return error.message;
+}
+var UnsupportedLogicalCapabilityError = class extends Error {
+	queryError;
+	constructor(capability, context) {
+		const error = queryErrors.unsupportedCapability(capability, context);
+		super(error.message);
+		this.name = "UnsupportedLogicalCapabilityError";
+		this.queryError = error;
+	}
+};
+var UnresolvableDatasetError = class extends Error {
+	queryError;
+	constructor(dimensions, filterDims = []) {
+		const error = queryErrors.unresolvableDataset(dimensions, filterDims);
+		super(error.message);
+		this.name = "UnresolvableDatasetError";
+		this.queryError = error;
+	}
+};
+function queryErrorToException(error) {
+	switch (error.kind) {
+		case "unsupported-capability": return new UnsupportedLogicalCapabilityError(error.capability, error.context);
+		case "unresolvable-dataset": return new UnresolvableDatasetError(error.dimensions, error.filterDims);
+		default: {
+			const exception = new Error(error.message);
+			if ("cause" in error && error.cause !== void 0) exception.cause = error.cause;
+			exception.queryError = error;
+			return exception;
+		}
+	}
+}
 const DATE_OPERATORS = [
 	"gte",
 	"gt",
@@ -1641,8 +1793,8 @@ function normalizeFilter(input) {
 	if (isWireFilter(input)) return convertWireGroup(input) ?? void 0;
 	return input;
 }
-function normalizeBuilderState(state) {
-	if (!state || typeof state !== "object") throw new Error("Invalid state");
+function normalizeBuilderStateResult(state) {
+	if (!state || typeof state !== "object") return err(queryErrors.invalidBuilderState(state));
 	const s = state;
 	const normalized = {
 		dimensions: s.dimensions,
@@ -1655,7 +1807,10 @@ function normalizeBuilderState(state) {
 		aggregationType: s.aggregationType
 	};
 	if (typeof s.searchType === "string" && KNOWN_SEARCH_TYPES.has(s.searchType)) normalized.searchType = s.searchType;
-	return normalized;
+	return ok(normalized);
+}
+function normalizeBuilderState(state) {
+	return unwrapResult(normalizeBuilderStateResult(state), queryErrorToException);
 }
 function extractSpecialFilters(filter) {
 	if (!filter) return {};
@@ -1735,9 +1890,9 @@ function extractSearchType(state) {
 	if (typeof raw !== "string" || raw.length === 0) return void 0;
 	return KNOWN_SEARCH_TYPES.has(raw) ? raw : void 0;
 }
-function resolveToBody(state) {
+function resolveToBodyResult(state) {
 	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)))");
+	if (!startDate || !endDate) return err(queryErrors.missingDateRange());
 	const body = {
 		dimensions: state.dimensions,
 		startDate,
@@ -1746,16 +1901,16 @@ function resolveToBody(state) {
 	const resolvedType = state.searchType ?? searchType;
 	if (resolvedType) body.type = resolvedType;
 	if (state.rowLimit !== void 0) {
-		if (!Number.isInteger(state.rowLimit) || state.rowLimit < 1) throw new Error(`rowLimit must be a positive integer, got ${state.rowLimit}`);
+		if (!Number.isInteger(state.rowLimit) || state.rowLimit < 1) return err(queryErrors.invalidRowLimit(state.rowLimit));
 		body.rowLimit = state.rowLimit;
 	}
 	if (state.startRow !== void 0) {
-		if (!Number.isInteger(state.startRow) || state.startRow < 0) throw new Error(`startRow must be a non-negative integer, got ${state.startRow}`);
+		if (!Number.isInteger(state.startRow) || state.startRow < 0) return err(queryErrors.invalidStartRow(state.startRow));
 		if (state.startRow > 0) body.startRow = state.startRow;
 	}
 	const hasHour = state.dimensions?.includes("hour");
-	if (hasHour && state.dataState !== "hourly_all") throw new Error("hour dimension requires dataState: \"hourly_all\"");
-	if (state.dataState === "hourly_all" && !hasHour) throw new Error("dataState: \"hourly_all\" requires grouping by hour dimension");
+	if (hasHour && state.dataState !== "hourly_all") return err(queryErrors.hourDimensionRequiresHourlyState());
+	if (state.dataState === "hourly_all" && !hasHour) return err(queryErrors.hourlyStateRequiresHourDimension());
 	if (state.dataState) body.dataState = state.dataState;
 	const filterGroups = resolveFilter(dimensionFilter);
 	if (filterGroups.length > 0) body.dimensionFilterGroups = filterGroups;
@@ -1764,20 +1919,23 @@ function resolveToBody(state) {
 		const apiLeafFilters = filterGroups.flatMap((g) => g.filters ?? []);
 		const filtersByPage = apiLeafFilters.some((f) => f.dimension === "page");
 		if (state.aggregationType === "byProperty") {
-			if (body.type === "discover" || body.type === "googleNews") throw new Error("aggregationType: \"byProperty\" is not supported for type \"discover\" or \"googleNews\"");
-			if (groupsByPage || filtersByPage) throw new Error("aggregationType: \"byProperty\" is not allowed when grouping or filtering by page");
+			if (body.type === "discover" || body.type === "googleNews") return err(queryErrors.byPropertyUnsupportedSearchType());
+			if (groupsByPage || filtersByPage) return err(queryErrors.byPropertyNotAllowedWithPage());
 		}
 		if (state.aggregationType === "byNewsShowcasePanel") {
-			if (body.type !== "discover" && body.type !== "googleNews") throw new Error("aggregationType: \"byNewsShowcasePanel\" requires type \"discover\" or \"googleNews\"");
-			if (groupsByPage || filtersByPage) throw new Error("aggregationType: \"byNewsShowcasePanel\" is not allowed when grouping or filtering by page");
+			if (body.type !== "discover" && body.type !== "googleNews") return err(queryErrors.byNewsShowcaseRequiresSearchType());
+			if (groupsByPage || filtersByPage) return err(queryErrors.byNewsShowcaseNotAllowedWithPage());
 			const saFilters = apiLeafFilters.filter((f) => f.dimension === "searchAppearance");
 			const hasNewsShowcase = saFilters.some((f) => f.operator === "equals" && f.expression === "NEWS_SHOWCASE");
 			const hasOther = saFilters.some((f) => !(f.operator === "equals" && f.expression === "NEWS_SHOWCASE"));
-			if (!hasNewsShowcase || hasOther) throw new Error("aggregationType: \"byNewsShowcasePanel\" requires a searchAppearance equals \"NEWS_SHOWCASE\" filter and no other searchAppearance filter");
+			if (!hasNewsShowcase || hasOther) return err(queryErrors.byNewsShowcaseRequiresShowcaseFilter());
 		}
 		body.aggregationType = state.aggregationType;
 	}
-	return body;
+	return ok(body);
+}
+function resolveToBody(state) {
+	return unwrapResult(resolveToBodyResult(state), queryErrorToException);
 }
 function isApiFilter(f) {
 	return !isMetricOperator(f.operator) && !isSpecialOperator(f.operator);
@@ -2031,12 +2189,6 @@ function between(column, start, 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;
@@ -2079,17 +2231,6 @@ function isDatasetResolvable(dimensions, filterDims = []) {
 	if (needed.size === 0) return true;
 	return RESOLVABLE_DIMENSION_FAMILIES.some((family) => [...needed].every((d) => family.has(d)));
 }
-var UnresolvableDatasetError = class extends Error {
-	constructor(dimensions, filterDims = []) {
-		const grouped = dimensions.filter((d) => !TIME_AXIS_DIMENSIONS.has(d));
-		const filtered = filterDims.filter((d) => !TIME_AXIS_DIMENSIONS.has(d));
-		super(`Cannot resolve a [${grouped.join(", ")}] breakdown filtered by [${filtered.join(", ")}] from stored data: these dimensions live in separate per-dimension tables. Only the live GSC API computes cross-dimension aggregates.`);
-		this.name = "UnresolvableDatasetError";
-	}
-};
-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;
@@ -2105,20 +2246,19 @@ function toLogicalDimensionFilter(filter) {
 		expression2: filter.expression2
 	};
 }
-function buildDimensionFilterTree(filter, capabilities) {
+function buildDimensionFilterTree(filter) {
 	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);
+		const sub = buildDimensionFilterTree(g);
 		if (sub) children.push(sub);
 	}
 	if (children.length === 0) return void 0;
@@ -2129,11 +2269,12 @@ function buildDimensionFilterTree(filter, capabilities) {
 		children
 	};
 }
-function buildLogicalPlan(state, capabilities = {}) {
+function buildLogicalPlanResult(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)");
+	if (!startDate || !endDate) return err(queryErrors.missingDateRange());
 	const allFilters = collectInternalFilters(normalizedFilter);
+	if (!capabilities.regex && allFilters.some((f) => isDimensionLeaf(f) && isRegexOperator(f.operator))) return err(queryErrors.unsupportedCapability("regex", "logical plan"));
 	const metricFilters = extractMetricFilters(normalizedFilter);
 	const specialFilters = extractSpecialOperatorFilters(normalizedFilter);
 	const prefilters = extractMetricFilters(normalizeFilter(state.prefilter));
@@ -2147,19 +2288,17 @@ function buildLogicalPlan(state, capabilities = {}) {
 			queryParams[filter.dimension] = filter.expression;
 			continue;
 		}
-		const operator = filter.operator;
-		requireCapability(capabilities, "regex", isRegexOperator(operator), "logical plan");
 		dimensionFilters.push({
 			dimension: filter.dimension,
-			operator,
+			operator: filter.operator,
 			expression: filter.expression,
 			expression2: filter.expression2
 		});
 	}
-	const dimensionFilterTree = buildDimensionFilterTree(normalizedFilter, capabilities);
+	const dimensionFilterTree = buildDimensionFilterTree(normalizedFilter);
 	const filterDims = dimensionFilters.map((filter) => filter.dimension);
-	if (!isDatasetResolvable(state.dimensions, filterDims)) throw new UnresolvableDatasetError(state.dimensions, filterDims);
-	return {
+	if (!isDatasetResolvable(state.dimensions, filterDims)) return err(queryErrors.unresolvableDataset(state.dimensions, filterDims));
+	return ok({
 		dataset: inferDataset(state.dimensions, filterDims),
 		dimensions: [...state.dimensions],
 		groupByDimensions: state.dimensions.filter((d) => d !== "date"),
@@ -2193,18 +2332,26 @@ function buildLogicalPlan(state, capabilities = {}) {
 		orderBy: state.orderBy,
 		rowLimit: state.rowLimit,
 		startRow: state.startRow
-	};
+	});
 }
-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 {
-		current: currentPlan,
-		previous: previousPlan,
+function buildLogicalPlan(state, capabilities = {}) {
+	return unwrapResult(buildLogicalPlanResult(state, capabilities), queryErrorToException);
+}
+function buildLogicalComparisonPlanResult(current, previous, capabilities = {}, comparisonFilter) {
+	if (!capabilities.comparisonJoin) return err(queryErrors.unsupportedCapability("comparisonJoin", "logical comparison plan"));
+	const currentResult = buildLogicalPlanResult(current, capabilities);
+	if (!currentResult.ok) return currentResult;
+	const previousResult = buildLogicalPlanResult(previous, capabilities);
+	if (!previousResult.ok) return previousResult;
+	if (currentResult.value.dataset !== previousResult.value.dataset && !capabilities.multiDataset) return err(queryErrors.unsupportedCapability("multiDataset", "logical comparison plan"));
+	return ok({
+		current: currentResult.value,
+		previous: previousResult.value,
 		comparisonFilter
-	};
+	});
+}
+function buildLogicalComparisonPlan(current, previous, capabilities = {}, comparisonFilter) {
+	return unwrapResult(buildLogicalComparisonPlanResult(current, previous, capabilities, comparisonFilter), queryErrorToException);
 }
 function today() {
 	return currentPstDate();
@@ -2212,4 +2359,4 @@ function today() {
 function daysAgo(n) {
 	return daysAgoPst(n);
 }
-export { Countries, Devices, SearchTypes, UnsupportedLogicalCapabilityError, and, between, buildLogicalComparisonPlan, buildLogicalPlan, clicks, contains, country, ctr, currentPstDate, date, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, gsc, gt, gte, hour, impressions, inArray, isJsonFilter, like, lt, lte, ne, normalizeBuilderState, normalizeFilter, not, notRegex, or, page, parseJsonFilter, position, query, queryCanonical, regex, searchAppearance, searchType, today, topLevel };
+export { Countries, Devices, SearchTypes, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, and, between, buildLogicalComparisonPlan, buildLogicalComparisonPlanResult, buildLogicalPlan, buildLogicalPlanResult, clicks, contains, country, ctr, currentPstDate, date, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, formatQueryError, gsc, gt, gte, hour, impressions, inArray, isJsonFilter, isQueryError, like, lt, lte, ne, normalizeBuilderState, normalizeBuilderStateResult, normalizeFilter, not, notRegex, or, page, parseJsonFilter, position, query, queryCanonical, queryErrorToException, queryErrors, regex, resolveToBody, resolveToBodyResult, searchAppearance, searchType, today, topLevel };

package/dist/query/plan.d.mts

@@ -1,6 +1,15 @@
 import { TableName } from "@gscdump/contracts";
 type GscDataState = 'final' | 'all' | 'hourly_all';
 type GscAggregationType = 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel';
+interface Ok<A> {
+  readonly ok: true;
+  readonly value: A;
+}
+interface Err<E> {
+  readonly ok: false;
+  readonly error: E;
+}
+type Result<A, E> = Ok<A> | Err<E>;
 declare const _default: {
   name: string;
   'alpha-2': string;
@@ -76,6 +85,62 @@ interface BuilderState {
   /** GSC search corpus. Wins over any `searchType` filter when both are set. */
   searchType?: SearchType;
 }
+type QueryErrorKind = 'missing-date-range' | 'invalid-row-limit' | 'invalid-start-row' | 'invalid-data-state' | 'invalid-aggregation-type' | 'invalid-builder-state' | 'unsupported-capability' | 'unresolvable-dataset';
+type QueryError = {
+  kind: 'missing-date-range';
+  message: string;
+} | {
+  kind: 'invalid-row-limit';
+  value: unknown;
+  message: string;
+} | {
+  kind: 'invalid-start-row';
+  value: unknown;
+  message: string;
+} | {
+  kind: 'invalid-data-state';
+  message: string;
+} | {
+  kind: 'invalid-aggregation-type';
+  message: string;
+} | {
+  kind: 'invalid-builder-state';
+  message: string;
+  cause?: unknown;
+} | {
+  kind: 'unsupported-capability';
+  capability: string;
+  context: string;
+  message: string;
+} | {
+  kind: 'unresolvable-dataset';
+  dimensions: readonly Dimension[];
+  filterDims: readonly Dimension[];
+  message: string;
+};
+/**
+ * Thrown when a query needs a planner capability (regex pushdown, comparison
+ * joins, multi-dataset reads) the target engine lacks. Engines catch it to fall
+ * back to the live GSC API. Carries the typed `queryError` value so a caller can
+ * read the modelled failure instead of parsing the message.
+ */
+declare class UnsupportedLogicalCapabilityError extends Error {
+  readonly queryError: Extract<QueryError, {
+    kind: 'unsupported-capability';
+  }>;
+  constructor(capability: string, context: string);
+}
+/**
+ * Thrown when a query's grouped + filtered dimensions span more than one stored
+ * dataset. Replaces the resolver's raw "unknown column" error so hosts can map
+ * it to a 4xx instead of leaking an opaque 500. Carries the typed `queryError`.
+ */
+declare class UnresolvableDatasetError extends Error {
+  readonly queryError: Extract<QueryError, {
+    kind: 'unresolvable-dataset';
+  }>;
+  constructor(dimensions: readonly Dimension[], filterDims?: readonly Dimension[]);
+}
 type LogicalDataset = TableName;
 type ComparisonFilter = 'new' | 'lost' | 'improving' | 'declining';
 interface PlannerCapabilities {
@@ -133,9 +198,6 @@ interface LogicalComparisonPlan {
   previous: LogicalQueryPlan;
   comparisonFilter?: ComparisonFilter;
 }
-declare class UnsupportedLogicalCapabilityError extends Error {
-  constructor(capability: keyof PlannerCapabilities, context: string);
-}
 declare function inferDataset(dimensions: readonly Dimension[], filterDims?: readonly Dimension[]): LogicalDataset;
 /**
  * True when every grouped + filtered dimension fits inside one stored dataset,
@@ -145,14 +207,6 @@ declare function inferDataset(dimensions: readonly Dimension[], filterDims?: rea
  * time.
  */
 declare function isDatasetResolvable(dimensions: readonly Dimension[], filterDims?: readonly Dimension[]): boolean;
-/**
- * Thrown when a query's grouped + filtered dimensions span more than one
- * stored dataset. Replaces the resolver's raw "unknown column" error so hosts
- * can map it to a 4xx instead of leaking an opaque 500.
- */
-declare class UnresolvableDatasetError extends Error {
-  constructor(dimensions: readonly Dimension[], filterDims?: readonly Dimension[]);
-}
 /**
  * `BuilderState`-level convenience for {@link isDatasetResolvable}: extracts
  * the state's dimension filters (the same way `buildLogicalPlan` does) and
@@ -160,6 +214,19 @@ declare class UnresolvableDatasetError extends Error {
  * 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 TableName, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, buildLogicalComparisonPlan, buildLogicalPlan, inferDataset, isDatasetResolvable, isStateResolvable };
+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 };