gscdump 3.5.0 → 3.6.0

package/dist/query/plan.d.mts

@@ -2,37 +2,37 @@ import { Result } from "../core/result.mjs";
 import { TableName } from "../contracts.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 {
+export type LogicalDataset = TableName;
+export type ComparisonFilter = 'new' | 'lost' | 'improving' | 'declining';
+export interface PlannerCapabilities {
   regex?: boolean;
   multiDataset?: boolean;
   comparisonJoin?: boolean;
   windowTotals?: boolean;
 }
-interface LogicalDimensionFilter {
+export interface LogicalDimensionFilter {
   dimension: Dimension;
   operator: FilterOperator;
   expression: string;
   expression2?: string;
 }
-interface LogicalMetricFilter {
+export interface LogicalMetricFilter {
   metric: Metric;
   operator: MetricOperator;
   expression: number;
   expression2?: number;
 }
-interface LogicalFilterLeaf {
+export interface LogicalFilterLeaf {
   kind: 'leaf';
   filter: LogicalDimensionFilter;
 }
-interface LogicalFilterGroup {
+export interface LogicalFilterGroup {
   kind: 'group';
   groupType: 'and' | 'or';
   children: LogicalFilterNode[];
 }
-type LogicalFilterNode = LogicalFilterLeaf | LogicalFilterGroup;
-interface LogicalQueryPlan {
+export type LogicalFilterNode = LogicalFilterLeaf | LogicalFilterGroup;
+export interface LogicalQueryPlan {
   dataset: LogicalDataset;
   dimensions: Dimension[];
   groupByDimensions: Dimension[];
@@ -54,12 +54,12 @@ interface LogicalQueryPlan {
   rowLimit?: number;
   startRow?: number;
 }
-interface LogicalComparisonPlan {
+export interface LogicalComparisonPlan {
   current: LogicalQueryPlan;
   previous: LogicalQueryPlan;
   comparisonFilter?: ComparisonFilter;
 }
-declare function inferDataset(dimensions: readonly Dimension[], filterDims?: readonly Dimension[]): LogicalDataset;
+export 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
@@ -67,27 +67,27 @@ declare function inferDataset(dimensions: readonly Dimension[], filterDims?: rea
  * 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;
+export 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;
+export 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;
+export declare function buildLogicalPlanResult(input: BuilderState, capabilities?: PlannerCapabilities): Result<LogicalQueryPlan, QueryError>;
+export 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 };
+export declare function buildLogicalComparisonPlanResult(current: BuilderState, previous: BuilderState, capabilities?: PlannerCapabilities, comparisonFilter?: ComparisonFilter): Result<LogicalComparisonPlan, QueryError>;
+export declare function buildLogicalComparisonPlan(current: BuilderState, previous: BuilderState, capabilities?: PlannerCapabilities, comparisonFilter?: ComparisonFilter): LogicalComparisonPlan;
+export { type QueryError, type QueryErrorKind, type TableName, UnresolvableDatasetError, UnsupportedLogicalCapabilityError };

package/dist/query/plan.mjs

@@ -1,7 +1,7 @@
 import { err, ok, unwrapResult } from "../core/result.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";
+import { extractDateRange, extractMetricFilters, extractSpecialOperatorFilters, normalizeBuilderStateResult, normalizeFilter } from "./resolver.mjs";
 function collectInternalFilters(filter) {
 	if (!filter || !("_filters" in filter)) return [];
 	const flat = filter._filters;
@@ -86,15 +86,18 @@ function buildDimensionFilterTree(filter) {
 		children
 	};
 }
-function buildLogicalPlanResult(state, capabilities = {}) {
-	const normalizedFilter = normalizeFilter(state.filter);
+function buildLogicalPlanResult(input, capabilities = {}) {
+	const parsed = normalizeBuilderStateResult(input);
+	if (!parsed.ok) return parsed;
+	const state = parsed.value;
+	const normalizedFilter = state.filter;
 	const { startDate, endDate } = extractDateRange(normalizedFilter);
 	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 normalizedPrefilter = normalizeFilter(state.prefilter);
+	const normalizedPrefilter = state.prefilter;
 	const prefilters = extractMetricFilters(normalizedPrefilter);
 	const queryParams = {};
 	const dimensionFilters = [];

package/dist/query/resolver.d.mts

@@ -3,31 +3,23 @@ import { GscSearchAnalyticsRequest } from "../contracts.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): {
+export declare function normalizeFilter(input?: FilterInput): Filter<any> | undefined;
+/** Parse an untrusted query body. Expected input failures stay in the error channel. */
+export declare function normalizeBuilderStateResult(state: unknown): Result<BuilderState, QueryError>;
+export declare function normalizeBuilderState(state: unknown): BuilderState;
+export declare function extractDateRange(input?: FilterInput): {
   startDate?: string;
   endDate?: string;
 };
-declare function extractMetricFilters(input?: FilterInput): InternalFilter[];
-declare function extractSpecialOperatorFilters(input?: FilterInput): InternalFilter[];
+export declare function extractMetricFilters(input?: FilterInput): InternalFilter[];
+export 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;
+export 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
@@ -35,6 +27,5 @@ declare function extractSearchType(state: BuilderState | undefined | null): Sear
  * 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 };
+export declare function resolveToBodyResult(input: BuilderState): Result<GscSearchAnalyticsRequest, QueryError>;
+export declare function resolveToBody(state: BuilderState): GscSearchAnalyticsRequest;

package/dist/query/resolver.mjs

@@ -2,91 +2,152 @@ import { err, ok, unwrapResult } from "../core/result.mjs";
 import { addDays } from "../core/gsc-dates.mjs";
 import { SearchTypes } from "./constants.mjs";
 import { queryErrorToException, queryErrors } from "./errors.mjs";
-import { isDateOperator, isMetricOperator, isQueryParam, isSpecialOperator } from "./operator-meta.mjs";
+import { isDateOperator, isMetric, isMetricOperator, isQueryParam, isSpecialOperator } from "./operator-meta.mjs";
+const KNOWN_DIMENSIONS = /* @__PURE__ */ new Set([
+	"page",
+	"query",
+	"queryCanonical",
+	"country",
+	"device",
+	"date",
+	"hour",
+	"searchAppearance"
+]);
+const FILTER_OPERATORS = /* @__PURE__ */ new Set([
+	"equals",
+	"notEquals",
+	"contains",
+	"notContains",
+	"includingRegex",
+	"excludingRegex"
+]);
 const KNOWN_SEARCH_TYPES = new Set(Object.values(SearchTypes));
-function isWireGroupType(type) {
-	return type === "and" || type === "or";
-}
-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 isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function convertWireGroup(alt) {
-	if (!isWireGroupType(alt.type)) {
-		const leaf = convertWireLeaf(alt);
-		return leaf ? { _filters: [leaf] } : null;
-	}
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isCalendarDate(value) {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+	const parsed = /* @__PURE__ */ new Date(`${value}T00:00:00Z`);
+	return Number.isFinite(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+function parseFilterResult(input, ancestors = /* @__PURE__ */ new Set()) {
+	if (input === void 0) return ok(void 0);
+	if (!isRecord(input) || ancestors.has(input)) return err(queryErrors.malformedFilterLeaf());
+	ancestors.add(input);
+	const invalid = () => err(queryErrors.malformedFilterLeaf());
 	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);
+	const wire = !("_filters" in input);
+	const groupType = wire ? input.type : input._groupType;
+	const isGroup = groupType === "and" || groupType === "or";
+	if (!wire && groupType !== void 0 && !isGroup) return invalid();
+	const values = wire ? isGroup ? input.filters : [input] : input._filters;
+	if (!Array.isArray(values)) return invalid();
+	for (const value of values) {
+		if (!isRecord(value)) return invalid();
+		if (wire && (value.type === "and" || value.type === "or")) {
+			const parsed = parseFilterResult(value, ancestors);
+			if (!parsed.ok) return parsed;
+			if (parsed.value) nested.push(parsed.value);
+			continue;
+		}
+		const dimension = wire ? value.column : value.dimension;
+		const operator = wire ? value.type === "eq" ? "equals" : value.type === "ne" ? "notEquals" : value.type : value.operator;
+		const between = operator === "between" || operator === "metricBetween";
+		const expression = wire ? between ? value.from : value.value : value.expression;
+		const expression2 = wire ? between ? value.to : void 0 : value.expression2;
+		if (typeof dimension !== "string" || !dimension || typeof operator !== "string" || !operator || typeof expression !== "string" || expression2 !== void 0 && typeof expression2 !== "string" || between && expression2 === void 0) return invalid();
+		if (!KNOWN_DIMENSIONS.has(dimension) && !isMetric(dimension) && !isQueryParam(dimension)) return invalid();
+		if (!FILTER_OPERATORS.has(operator) && !isDateOperator(operator) && !isMetricOperator(operator) && !isSpecialOperator(operator)) return invalid();
+		if (dimension === "searchType" && (operator !== "equals" || !KNOWN_SEARCH_TYPES.has(expression))) return invalid();
+		if (isDateOperator(operator) && (dimension !== "date" || !isCalendarDate(expression) || expression2 !== void 0 && !isCalendarDate(expression2))) return invalid();
+		if (isMetricOperator(operator) && (!isMetric(dimension) || !expression.trim() || !Number.isFinite(Number(expression)) || expression2 !== void 0 && (!expression2.trim() || !Number.isFinite(Number(expression2))))) return invalid();
+		leaves.push({
+			dimension,
+			operator,
+			expression,
+			...expression2 !== void 0 ? { expression2 } : {}
+		});
 	}
-	if (leaves.length === 0 && nested.length === 0) return null;
-	return {
+	if (!wire && input._nestedGroups !== void 0) {
+		if (!Array.isArray(input._nestedGroups)) return invalid();
+		for (const group of input._nestedGroups) {
+			const parsed = parseFilterResult(group, ancestors);
+			if (!parsed.ok) return parsed;
+			if (!parsed.value) return invalid();
+			nested.push(parsed.value);
+		}
+	}
+	if (groupType === "or" && (leaves.length === 0 || nested.length > 0 || leaves.some((leaf) => leaf.dimension === "searchType" || leaf.dimension === "date" && isDateOperator(leaf.operator)))) return invalid();
+	ancestors.delete(input);
+	return ok({
 		_filters: leaves,
-		_nestedGroups: nested.length > 0 ? nested : void 0,
-		_groupType: alt.type
-	};
-}
-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);
+		...nested.length ? { _nestedGroups: nested } : {},
+		...isGroup ? { _groupType: groupType } : {}
+	});
 }
 function normalizeFilter(input) {
-	if (!input) return void 0;
-	if (isWireFilter(input)) return convertWireGroup(input) ?? void 0;
-	if (typeof input === "object" && Array.isArray(input._filters)) return input;
+	return unwrapResult(parseFilterResult(input), queryErrorToException);
 }
 function normalizeOrderBy(orderBy) {
+	if (Array.isArray(orderBy) && orderBy.length !== 1) return void 0;
 	const spec = Array.isArray(orderBy) ? orderBy[0] : orderBy;
 	if (!spec || typeof spec !== "object") return void 0;
 	const o = spec;
-	if (typeof o.column !== "string" || o.column.length === 0) return void 0;
+	if (typeof o.column !== "string" || !isMetric(o.column) && o.column !== "date") return void 0;
+	if (o.dir !== void 0 && (typeof o.dir !== "string" || !["asc", "desc"].includes(o.dir.toLowerCase()))) return void 0;
+	if (o.desc !== void 0 && typeof o.desc !== "boolean") return void 0;
 	const dir = typeof o.dir === "string" ? o.dir.toLowerCase() === "asc" ? "asc" : "desc" : o.desc === false ? "asc" : "desc";
+	if (typeof o.desc === "boolean" && o.desc !== (dir === "desc")) return void 0;
 	return {
 		column: o.column,
 		dir
 	};
 }
-function hasMalformedFilterLeaf(filter) {
-	if (!filter || typeof filter !== "object") return false;
-	if (Array.isArray(filter._filters)) {
-		for (const leaf of filter._filters) if (!leaf || typeof leaf !== "object" || typeof leaf.operator !== "string" || typeof leaf.dimension !== "string") return true;
-	}
-	if (Array.isArray(filter._nestedGroups)) {
-		for (const group of filter._nestedGroups) if (hasMalformedFilterLeaf(group)) return true;
-	}
-	return false;
-}
 function normalizeBuilderStateResult(state) {
-	if (!state || typeof state !== "object") return err(queryErrors.invalidBuilderState(state));
+	if (!isRecord(state)) return err(queryErrors.invalidBuilderState(state));
 	const s = state;
-	const filter = normalizeFilter(s.filter);
-	if (hasMalformedFilterLeaf(filter)) return err(queryErrors.malformedFilterLeaf());
-	const normalized = {
-		dimensions: Array.isArray(s.dimensions) ? s.dimensions : [],
+	const invalidState = (message) => err({
+		...queryErrors.invalidBuilderState(state),
+		message
+	});
+	if (s.dimensions !== void 0 && (!isStringArray(s.dimensions) || !s.dimensions.every((dimension) => KNOWN_DIMENSIONS.has(dimension)))) return invalidState(`dimensions must contain valid names: ${[...KNOWN_DIMENSIONS].join(", ")}.`);
+	if (s.metrics !== void 0 && (!isStringArray(s.metrics) || !s.metrics.every(isMetric))) return invalidState("metrics must contain clicks, impressions, ctr, or position.");
+	if (s.searchType !== void 0 && (typeof s.searchType !== "string" || !KNOWN_SEARCH_TYPES.has(s.searchType))) return invalidState(`searchType must be one of: ${[...KNOWN_SEARCH_TYPES].join(", ")}.`);
+	if (s.dataState !== void 0 && ![
+		"all",
+		"final",
+		"hourly_all"
+	].includes(s.dataState)) return invalidState("dataState must be all, final, or hourly_all.");
+	if (s.aggregationType !== void 0 && ![
+		"auto",
+		"byPage",
+		"byProperty",
+		"byNewsShowcasePanel"
+	].includes(s.aggregationType)) return invalidState("aggregationType must be auto, byPage, byProperty, or byNewsShowcasePanel.");
+	if (s.rowLimit !== void 0 && (!Number.isSafeInteger(s.rowLimit) || s.rowLimit < 1)) return err(queryErrors.invalidRowLimit(s.rowLimit));
+	if (s.startRow !== void 0 && (!Number.isSafeInteger(s.startRow) || s.startRow < 0)) return err(queryErrors.invalidStartRow(s.startRow));
+	const orderBy = normalizeOrderBy(s.orderBy);
+	if (s.orderBy !== void 0 && orderBy === void 0) return invalidState("orderBy requires a metric or date column and a consistent asc or desc direction.");
+	const filter = parseFilterResult(s.filter);
+	if (!filter.ok) return filter;
+	const prefilter = parseFilterResult(s.prefilter);
+	if (!prefilter.ok) return prefilter;
+	return ok({
+		dimensions: s.dimensions ?? [],
 		metrics: s.metrics,
-		filter,
-		orderBy: normalizeOrderBy(s.orderBy),
+		filter: filter.value,
+		prefilter: prefilter.value,
+		orderBy,
 		rowLimit: s.rowLimit,
 		startRow: s.startRow,
 		dataState: s.dataState,
-		aggregationType: s.aggregationType
-	};
-	if (typeof s.searchType === "string" && KNOWN_SEARCH_TYPES.has(s.searchType)) normalized.searchType = s.searchType;
-	return ok(normalized);
+		aggregationType: s.aggregationType,
+		searchType: s.searchType
+	});
 }
 function normalizeBuilderState(state) {
 	return unwrapResult(normalizeBuilderStateResult(state), queryErrorToException);
@@ -167,7 +228,10 @@ function extractSearchType(state) {
 	if (typeof raw !== "string" || raw.length === 0) return void 0;
 	return KNOWN_SEARCH_TYPES.has(raw) ? raw : void 0;
 }
-function resolveToBodyResult(state) {
+function resolveToBodyResult(input) {
+	const parsed = normalizeBuilderStateResult(input);
+	if (!parsed.ok) return parsed;
+	const state = parsed.value;
 	const { startDate, endDate, searchType, dimensionFilter } = extractSpecialFilters(state.filter);
 	if (!startDate || !endDate) return err(queryErrors.missingDateRange());
 	const body = {

package/dist/query/types.d.mts

@@ -1,6 +1,6 @@
 import { GscAggregationType, GscDataState } from "../contracts.mjs";
 import { Country, Device, SearchType } from "./constants.mjs";
-interface DimensionValueMap {
+export interface DimensionValueMap {
   query: string;
   queryCanonical: string;
   page: string;
@@ -11,53 +11,53 @@ interface DimensionValueMap {
   /** Hour bucket — ISO-8601 with PT offset, e.g. `2025-07-14T13:00:00-07:00`. Use with `dataState: 'hourly_all'`. */
   hour: string;
 }
-type Dimension = keyof DimensionValueMap;
-interface QueryParamValueMap {
+export type Dimension = keyof DimensionValueMap;
+export interface QueryParamValueMap {
   searchType: SearchType;
 }
-type QueryParamName = keyof QueryParamValueMap;
-interface Column<D extends Dimension> {
+export type QueryParamName = keyof QueryParamValueMap;
+export interface Column<D extends Dimension> {
   readonly __columnBrand: 'gscdump.Column';
   readonly dimension: D;
 }
-interface QueryParam<P extends QueryParamName> {
+export interface QueryParam<P extends QueryParamName> {
   readonly __queryParamBrand: 'gscdump.QueryParam';
   readonly param: P;
 }
-type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
-type DateOperator = 'gte' | 'gt' | 'lte' | 'lt' | 'between';
-type MetricOperator = 'metricGte' | 'metricGt' | 'metricLte' | 'metricLt' | 'metricBetween';
-type SpecialOperator = 'topLevel';
-interface InternalFilter {
+export type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
+export type DateOperator = 'gte' | 'gt' | 'lte' | 'lt' | 'between';
+export type MetricOperator = 'metricGte' | 'metricGt' | 'metricLte' | 'metricLt' | 'metricBetween';
+export type SpecialOperator = 'topLevel';
+export interface InternalFilter {
   dimension: Dimension | QueryParamName | Metric;
   operator: FilterOperator | DateOperator | MetricOperator | SpecialOperator;
   expression: string;
   expression2?: string;
 }
-interface Filter<C = object> {
+export interface Filter<C = object> {
   readonly __filterBrand: 'gscdump.Filter';
   readonly _constraints: C;
   readonly _filters: InternalFilter[];
   readonly _nestedGroups?: Filter<any>[];
   readonly _groupType?: 'and' | 'or';
 }
-type MergeConstraints<F extends Filter<any>[]> = UnionToIntersection<F[number]['_constraints']>;
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
-interface GSCResult<D extends Dimension[], C> {
+export type MergeConstraints<F extends Filter<any>[]> = UnionToIntersection<F[number]['_constraints']>;
+export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+export interface GSCResult<D extends Dimension[], C> {
   rows: Array<GSCRow<D, C>>;
 }
-type GSCRow<D extends Dimension[], C> = { [K in D[number]]: K extends keyof C ? C[K] : DimensionValueMap[K]; } & {
+export type GSCRow<D extends Dimension[], C> = { [K in D[number]]: K extends keyof C ? C[K] : DimensionValueMap[K]; } & {
   clicks: number;
   impressions: number;
   ctr: number;
   position: number;
 };
-type Metric = 'clicks' | 'impressions' | 'ctr' | 'position';
-interface MetricColumn<M extends Metric> {
+export type Metric = 'clicks' | 'impressions' | 'ctr' | 'position';
+export interface MetricColumn<M extends Metric> {
   readonly __metricColumnBrand: 'gscdump.MetricColumn';
   readonly metric: M;
 }
-interface BuilderState {
+export interface BuilderState {
   dimensions: Dimension[];
   metrics?: Metric[];
   filter?: Filter<any>;
@@ -75,16 +75,15 @@ interface BuilderState {
   /** GSC search corpus. Wins over any `searchType` filter when both are set. */
   searchType?: SearchType;
 }
-interface JsonInternalFilter {
+export interface JsonInternalFilter {
   dimension: string;
   operator: string;
   expression: string;
   expression2?: string;
 }
-interface JsonFilter {
+export interface JsonFilter {
   _filters: JsonInternalFilter[];
   _nestedGroups?: JsonFilter[];
   _groupType?: 'and' | 'or';
 }
-type FilterInput = Filter<any> | JsonFilter;
-export { BuilderState, Column, DateOperator, Dimension, DimensionValueMap, Filter, FilterInput, FilterOperator, GSCResult, GSCRow, InternalFilter, JsonFilter, JsonInternalFilter, MergeConstraints, Metric, MetricColumn, MetricOperator, QueryParam, QueryParamName, QueryParamValueMap, SpecialOperator, UnionToIntersection };
+export type FilterInput = Filter<any> | JsonFilter;

package/dist/query/utils/dayjs.d.mts

@@ -1,3 +1,2 @@
-declare function currentPstDate(): string;
-declare function daysAgoPst(n: number): string;
-export { currentPstDate, daysAgoPst };
+export declare function currentPstDate(): string;
+export declare function daysAgoPst(n: number): string;

package/dist/sitemap-identity.d.mts

@@ -1,31 +1,30 @@
-type SitemapIdentityResult = {
+export type SitemapIdentityResult = {
   _tag: 'ok';
   url: string;
 } | {
   _tag: 'invalid';
   reason: 'credentials' | 'empty' | 'invalid_url' | 'off_origin';
 };
-interface SitemapEvidenceRecord {
+export interface SitemapEvidenceRecord {
   path: string;
   lastDownloaded?: string | null;
   fetchedAt?: number | null;
 }
-interface ScopedSitemapRecords<T extends SitemapEvidenceRecord> {
+export interface ScopedSitemapRecords<T extends SitemapEvidenceRecord> {
   sitemaps: Array<T & {
     path: string;
   }>;
   excludedCount: number;
   duplicateCount: number;
 }
-interface SitemapContentEntry {
+export interface SitemapContentEntry {
   loc: string;
 }
-declare function canonicalSitemapIdentity(path: string, site?: string): SitemapIdentityResult;
-declare function sameSitemapIdentity(left: string, right: string, site?: string): boolean;
-declare function scopeSitemapRecords<T extends SitemapEvidenceRecord>(records: readonly T[], site?: string): ScopedSitemapRecords<T>;
+export declare function canonicalSitemapIdentity(path: string, site?: string): SitemapIdentityResult;
+export declare function sameSitemapIdentity(left: string, right: string, site?: string): boolean;
+export declare function scopeSitemapRecords<T extends SitemapEvidenceRecord>(records: readonly T[], site?: string): ScopedSitemapRecords<T>;
 /**
  * Versioned exact membership digest. This deliberately does not use the
  * analytics-only `urlMatchKey` normalizer.
  */
-declare function sitemapContentHash(entries: readonly SitemapContentEntry[]): Promise<string>;
-export { ScopedSitemapRecords, SitemapContentEntry, SitemapEvidenceRecord, SitemapIdentityResult, canonicalSitemapIdentity, sameSitemapIdentity, scopeSitemapRecords, sitemapContentHash };
+export declare function sitemapContentHash(entries: readonly SitemapContentEntry[]): Promise<string>;

package/dist/tenant.d.mts

@@ -1,4 +1,4 @@
-declare function encodeSiteId(siteUrl: string): string;
+export declare function encodeSiteId(siteUrl: string): string;
 /**
  * Best-effort inverse of `encodeSiteId` for the common prefixes. Lossy
  * (`encodeSiteId` collapses non-word chars to `_` and strips trailing
@@ -8,11 +8,10 @@ declare function encodeSiteId(siteUrl: string): string;
  * Returns the input unchanged when neither prefix is recognised, so callers
  * can pass through canonical site URLs without branching.
  */
-declare function decodeSiteId(encoded: string): string;
+export declare function decodeSiteId(encoded: string): string;
 /**
  * Normalize a siteUrl to the form Google APIs expect: domain properties get
  * the `sc-domain:` prefix added if missing, URL properties pass through.
  * Idempotent — safe to call on already-prefixed values.
  */
-declare function normalizeSiteUrl(siteUrl: string): string;
-export { decodeSiteId, encodeSiteId, normalizeSiteUrl };
+export declare function normalizeSiteUrl(siteUrl: string): string;

package/dist/url.d.mts

@@ -5,5 +5,4 @@
  *
  * Example: `https://www.Example.com/Foo/` → `example.com/foo`
  */
-declare function urlMatchKey(url: string): string | null;
-export { urlMatchKey };
+export declare function urlMatchKey(url: string): string | null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gscdump",
   "type": "module",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Direct Google Search Console and Bing Webmaster clients with typed queries and Indexing Evidence",
   "author": {
     "name": "Harlan Wilton",
@@ -113,7 +113,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@gscdump/contracts": "^3.5.0",
+    "@gscdump/contracts": "^3.6.0",
     "ofetch": "^1.5.1"
   },
   "scripts": {