gscdump 0.25.14 → 0.26.0

package/dist/query/plan.mjs

@@ -1,3 +1,139 @@
+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);
+}
+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.`
+		};
+	}
+};
+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",
@@ -1665,12 +1801,6 @@ function extractSpecialOperatorFilters(input) {
 	const nested = filter._nestedGroups?.flatMap((g) => extractSpecialOperatorFilters(g)) ?? [];
 	return [...special, ...nested];
 }
-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;
@@ -1713,21 +1843,10 @@ 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 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);
-}
 function isDimensionLeaf(filter) {
 	if (isMetric(filter.dimension)) return false;
 	if (filter.dimension === "date" && isDateOperator(filter.operator)) return false;
@@ -1743,20 +1862,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;
@@ -1767,11 +1885,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));
@@ -1785,19 +1904,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"),
@@ -1831,17 +1948,25 @@ 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);
 }
-export { UnresolvableDatasetError, UnsupportedLogicalCapabilityError, buildLogicalComparisonPlan, buildLogicalPlan, inferDataset, isDatasetResolvable, isStateResolvable };
+export { UnresolvableDatasetError, UnsupportedLogicalCapabilityError, buildLogicalComparisonPlan, buildLogicalComparisonPlanResult, buildLogicalPlan, buildLogicalPlanResult, inferDataset, isDatasetResolvable, isStateResolvable };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gscdump",
   "type": "module",
-  "version": "0.25.14",
+  "version": "0.26.0",
   "description": "Google Search Console API wrapper with typed query builder, streaming pagination, and SEO analysis functions",
   "author": {
     "name": "Harlan Wilton",
@@ -47,6 +47,11 @@
       "import": "./dist/query/plan.mjs",
       "default": "./dist/query/plan.mjs"
     },
+    "./result": {
+      "types": "./dist/core/result.d.mts",
+      "import": "./dist/core/result.mjs",
+      "default": "./dist/core/result.mjs"
+    },
     "./contracts": {
       "types": "./dist/contracts.d.mts",
       "import": "./dist/contracts.mjs",
@@ -78,7 +83,7 @@
     "defu": "^6.1.7",
     "ofetch": "^1.5.1",
     "ufo": "^1.6.4",
-    "@gscdump/contracts": "0.25.14"
+    "@gscdump/contracts": "0.26.0"
   },
   "devDependencies": {
     "@googleapis/indexing": "^6.0.1",