gscdump 0.19.1 → 0.19.3

package/dist/query/index.mjs

@@ -2042,6 +2042,30 @@ function inferDataset(dimensions, filterDims = []) {
 	if (has("device")) return "devices";
 	return "devices";
 }
+const RESOLVABLE_DIMENSION_FAMILIES = [
+	new Set([
+		"page",
+		"query",
+		"queryCanonical"
+	]),
+	new Set(["country"]),
+	new Set(["device"]),
+	new Set(["searchAppearance"])
+];
+const TIME_AXIS_DIMENSIONS = new Set(["date", "hour"]);
+function isDatasetResolvable(dimensions, filterDims = []) {
+	const needed = new Set([...dimensions, ...filterDims].filter((d) => !TIME_AXIS_DIMENSIONS.has(d)));
+	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);
 }
@@ -2113,6 +2137,7 @@ function buildLogicalPlan(state, capabilities = {}) {
 	}
 	const dimensionFilterTree = buildDimensionFilterTree(normalizedFilter, capabilities);
 	const filterDims = dimensionFilters.map((filter) => filter.dimension);
+	if (!isDatasetResolvable(state.dimensions, filterDims)) throw new UnresolvableDatasetError(state.dimensions, filterDims);
 	return {
 		dataset: inferDataset(state.dimensions, filterDims),
 		dimensions: [...state.dimensions],

package/dist/query/plan.d.mts

@@ -136,6 +136,30 @@ interface LogicalComparisonPlan {
 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,
+ * 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;
+/**
+ * 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
+ * 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;
 declare function buildLogicalPlan(state: BuilderState, capabilities?: PlannerCapabilities): LogicalQueryPlan;
 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, UnsupportedLogicalCapabilityError, buildLogicalComparisonPlan, buildLogicalPlan };
+export { ComparisonFilter, LogicalComparisonPlan, LogicalDataset, LogicalDimensionFilter, LogicalFilterGroup, LogicalFilterLeaf, LogicalFilterNode, LogicalMetricFilter, LogicalQueryPlan, PlannerCapabilities, type TableName, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, buildLogicalComparisonPlan, buildLogicalPlan, inferDataset, isDatasetResolvable, isStateResolvable };

package/dist/query/plan.mjs

@@ -1688,6 +1688,34 @@ function inferDataset(dimensions, filterDims = []) {
 	if (has("device")) return "devices";
 	return "devices";
 }
+const RESOLVABLE_DIMENSION_FAMILIES = [
+	new Set([
+		"page",
+		"query",
+		"queryCanonical"
+	]),
+	new Set(["country"]),
+	new Set(["device"]),
+	new Set(["searchAppearance"])
+];
+const TIME_AXIS_DIMENSIONS = new Set(["date", "hour"]);
+function isDatasetResolvable(dimensions, filterDims = []) {
+	const needed = new Set([...dimensions, ...filterDims].filter((d) => !TIME_AXIS_DIMENSIONS.has(d)));
+	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 isStateResolvable(state) {
+	const filterDims = collectInternalFilters(normalizeFilter(state.filter)).filter((f) => !isMetric(f.dimension)).filter((f) => !(f.dimension === "date" && isDateOperator(f.operator))).filter((f) => !(f.operator === "topLevel" || f.operator.startsWith("metric"))).filter((f) => !isQueryParam(f.dimension)).map((f) => f.dimension);
+	return isDatasetResolvable(state.dimensions, filterDims);
+}
 function requireCapability(capabilities, capability, enabled, context) {
 	if (enabled && !capabilities?.[capability]) throw new UnsupportedLogicalCapabilityError(capability, context);
 }
@@ -1759,6 +1787,7 @@ function buildLogicalPlan(state, capabilities = {}) {
 	}
 	const dimensionFilterTree = buildDimensionFilterTree(normalizedFilter, capabilities);
 	const filterDims = dimensionFilters.map((filter) => filter.dimension);
+	if (!isDatasetResolvable(state.dimensions, filterDims)) throw new UnresolvableDatasetError(state.dimensions, filterDims);
 	return {
 		dataset: inferDataset(state.dimensions, filterDims),
 		dimensions: [...state.dimensions],
@@ -1806,4 +1835,4 @@ function buildLogicalComparisonPlan(current, previous, capabilities = {}, compar
 		comparisonFilter
 	};
 }
-export { UnsupportedLogicalCapabilityError, buildLogicalComparisonPlan, buildLogicalPlan };
+export { UnresolvableDatasetError, UnsupportedLogicalCapabilityError, buildLogicalComparisonPlan, buildLogicalPlan, inferDataset, isDatasetResolvable, isStateResolvable };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gscdump",
   "type": "module",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "description": "Google Search Console API wrapper with typed query builder, streaming pagination, and SEO analysis functions",
   "author": {
     "name": "Harlan Wilton",
@@ -108,7 +108,7 @@
     "defu": "^6.1.7",
     "ofetch": "^1.5.1",
     "ufo": "^1.6.4",
-    "@gscdump/contracts": "0.19.1"
+    "@gscdump/contracts": "0.19.3"
   },
   "devDependencies": {
     "@googleapis/indexing": "^6.0.1",