gscdump 0.2.0 → 0.3.0

package/dist/analysis/index.d.mts

@@ -191,6 +191,7 @@ type Country = typeof Countries[keyof typeof Countries];
 //#region src/query/types.d.ts
 interface DimensionValueMap {
   query: string;
+  queryCanonical: string;
   page: string;
   country: Country;
   device: Device;
@@ -202,11 +203,18 @@ interface QueryParamValueMap {
   searchType: SearchType;
 }
 type QueryParamName = keyof QueryParamValueMap;
+declare const ColumnBrand: unique symbol;
+interface Column<D extends Dimension> {
+  readonly [ColumnBrand]: D;
+  readonly dimension: D;
+}
 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 {
-  dimension: Dimension | QueryParamName;
-  operator: FilterOperator | DateOperator;
+  dimension: Dimension | QueryParamName | Metric;
+  operator: FilterOperator | DateOperator | MetricOperator | SpecialOperator;
   expression: string;
   expression2?: string;
 }
@@ -224,17 +232,35 @@ type GSCRow<D extends Dimension[], C> = { [K in D[number]]: K extends keyof C ?
   ctr: number;
   position: number;
 };
+type Metric = 'clicks' | 'impressions' | 'ctr' | 'position';
+declare const MetricColumnBrand: unique symbol;
+interface MetricColumn<M extends Metric> {
+  readonly [MetricColumnBrand]: M;
+  readonly metric: M;
+}
 interface BuilderState {
   dimensions: Dimension[];
+  metrics?: Metric[];
   filter?: Filter<any>;
+  orderBy?: {
+    column: Metric | 'date';
+    dir: 'asc' | 'desc';
+  };
   rowLimit?: number;
   startRow?: number;
 }
 //#endregion
 //#region src/query/builder.d.ts
+type SelectableColumn = Column<Dimension> | MetricColumn<Metric>;
+type OrderableColumn = MetricColumn<Metric> | Column<'date'>;
+type ExtractDimensions<T extends SelectableColumn[]> = { [K in keyof T]: T[K] extends Column<infer D> ? D : never }[number] extends infer U ? Exclude<U, never>[] : never;
 interface GSCQueryBuilder<D extends Dimension[] = [], C = object> {
-  select: <T extends Dimension[]>(...dims: T) => GSCQueryBuilder<T, C>;
+  select: {
+    <T extends Dimension[]>(...dims: T): GSCQueryBuilder<T, C>;
+    <T extends SelectableColumn[]>(...cols: T): GSCQueryBuilder<ExtractDimensions<T> & Dimension[], C>;
+  };
   where: <F extends Filter<any>>(filter: F) => GSCQueryBuilder<D, C & F['_constraints']>;
+  orderBy: (col: OrderableColumn, dir: 'asc' | 'desc') => GSCQueryBuilder<D, C>;
   limit: (n: number) => GSCQueryBuilder<D, C>;
   offset: (n: number) => GSCQueryBuilder<D, C>;
   toBody: () => SearchAnalyticsQuery;

package/dist/analysis/index.mjs

@@ -229,9 +229,9 @@ function analyzeDecay(input, options = {}) {
 	});
 	const previousMap = /* @__PURE__ */ new Map();
 	for (const row of input.previous) {
-		const clicks = num(row.clicks);
-		if (clicks >= minPreviousClicks) previousMap.set(row.page, {
-			clicks,
+		const clicks$1 = num(row.clicks);
+		if (clicks$1 >= minPreviousClicks) previousMap.set(row.page, {
+			clicks: clicks$1,
 			position: num(row.position)
 		});
 	}
@@ -266,7 +266,21 @@ const DATE_OPERATORS = [
 	"lt",
 	"between"
 ];
+const METRIC_OPERATORS = [
+	"metricGte",
+	"metricGt",
+	"metricLte",
+	"metricLt",
+	"metricBetween"
+];
+const SPECIAL_OPERATORS = ["topLevel"];
 const QUERY_PARAMS = ["searchType"];
+function isMetricOperator(op) {
+	return METRIC_OPERATORS.includes(op);
+}
+function isSpecialOperator(op) {
+	return SPECIAL_OPERATORS.includes(op);
+}
 function isDateOperator(op) {
 	return DATE_OPERATORS.includes(op);
 }
@@ -305,7 +319,8 @@ function extractSpecialFilters(filter) {
 	}
 	else if (isQueryParam(f.dimension)) {
 		if (f.dimension === "searchType") searchType$1 = f.expression;
-	} else otherFilters.push(f);
+	} else if (isMetricOperator(f.operator) || isSpecialOperator(f.operator)) otherFilters.push(f);
+	else otherFilters.push(f);
 	if (filter._nestedGroups) for (const nested of filter._nestedGroups) {
 		const extracted = extractSpecialFilters(nested);
 		if (extracted.startDate) startDate = extracted.startDate;
@@ -340,19 +355,24 @@ function resolveToBody(state) {
 	if (filterGroups.length > 0) body.dimensionFilterGroups = filterGroups;
 	return body;
 }
+function isApiFilter(f) {
+	return !isMetricOperator(f.operator) && !isSpecialOperator(f.operator);
+}
 function resolveFilter(filter) {
 	if (!filter) return [];
 	const groups = [];
-	if ((filter._groupType ?? "and") === "or") {
-		if (filter._filters.length > 0) groups.push({
+	const groupType = filter._groupType ?? "and";
+	const apiFilters = filter._filters.filter(isApiFilter);
+	if (groupType === "or") {
+		if (apiFilters.length > 0) groups.push({
 			groupType: "or",
-			filters: filter._filters.map((f) => ({
+			filters: apiFilters.map((f) => ({
 				dimension: f.dimension,
 				operator: f.operator,
 				expression: f.expression
 			}))
 		});
-	} else if (filter._filters.length > 0) groups.push({ filters: filter._filters.map((f) => ({
+	} else if (apiFilters.length > 0) groups.push({ filters: apiFilters.map((f) => ({
 		dimension: f.dimension,
 		operator: f.operator,
 		expression: f.expression
@@ -363,12 +383,27 @@ function resolveFilter(filter) {
 
 //#endregion
 //#region src/query/builder.ts
+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(...dims) {
+		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: dims
+				dimensions,
+				metrics: metrics.length > 0 ? metrics : void 0
 			});
 		},
 		where(filter) {
@@ -377,6 +412,16 @@ function createBuilder(state) {
 				filter
 			});
 		},
+		orderBy(col, dir) {
+			const column = isMetricColumn(col) ? col.metric : col.dimension;
+			return createBuilder({
+				...state,
+				orderBy: {
+					column,
+					dir
+				}
+			});
+		},
 		limit(n) {
 			return createBuilder({
 				...state,
@@ -404,20 +449,37 @@ 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 clicks = createMetricColumn("clicks");
+const impressions = createMetricColumn("impressions");
+const ctr = createMetricColumn("ctr");
+const position = createMetricColumn("position");
 const searchType = createQueryParam("searchType");
 
 //#endregion
 //#region src/query/operators.ts
 function between(column, start, end) {
+	if ("metric" in column) return {
+		_constraints: {},
+		_filters: [{
+			dimension: column.metric,
+			operator: "metricBetween",
+			expression: String(start),
+			expression2: String(end)
+		}]
+	};
 	return {
 		_constraints: {},
 		_filters: [{
@@ -455,31 +517,31 @@ function analyzeMovers(input, options = {}) {
 	const declining = [];
 	const stable = [];
 	for (const row of input.current) {
-		const impressions = num(row.impressions);
-		const clicks = num(row.clicks);
-		const position = num(row.position);
-		if (impressions < minImpressions) continue;
+		const impressions$1 = num(row.impressions);
+		const clicks$1 = num(row.clicks);
+		const position$1 = num(row.position);
+		if (impressions$1 < minImpressions) continue;
 		const baseline = baselineMap.get(row.query) || {
 			clicks: 0,
 			impressions: 0,
 			position: 0,
 			page: null
 		};
-		const clicksChangePercent = percentDifference(clicks, baseline.clicks);
-		const impressionsChangePercent = percentDifference(impressions, baseline.impressions);
+		const clicksChangePercent = percentDifference(clicks$1, baseline.clicks);
+		const impressionsChangePercent = percentDifference(impressions$1, baseline.impressions);
 		const data = {
 			keyword: row.query,
 			page: pageMap.get(row.query) ?? null,
-			recentClicks: clicks,
-			recentImpressions: impressions,
-			recentPosition: position,
+			recentClicks: clicks$1,
+			recentImpressions: impressions$1,
+			recentPosition: position$1,
 			baselineClicks: Math.round(baseline.clicks),
 			baselineImpressions: Math.round(baseline.impressions),
 			baselinePosition: baseline.position,
-			clicksChange: clicks - Math.round(baseline.clicks),
+			clicksChange: clicks$1 - Math.round(baseline.clicks),
 			clicksChangePercent,
 			impressionsChangePercent,
-			positionChange: position - baseline.position
+			positionChange: position$1 - baseline.position
 		};
 		const absChange = Math.abs(clicksChangePercent / 100);
 		if (clicksChangePercent > 0 && absChange >= changeThreshold) rising.push(data);
@@ -520,21 +582,21 @@ const EXPECTED_CTR_BY_POSITION = {
 	9: .02,
 	10: .015
 };
-function getExpectedCtr(position) {
-	return EXPECTED_CTR_BY_POSITION[Math.round(Math.max(1, Math.min(position, 10)))] || .01;
+function getExpectedCtr(position$1) {
+	return EXPECTED_CTR_BY_POSITION[Math.round(Math.max(1, Math.min(position$1, 10)))] || .01;
 }
-function calculatePositionScore(position) {
-	if (position <= 3) return .2;
-	if (position > 50) return .1;
-	const distance = Math.abs(position - 11);
+function calculatePositionScore(position$1) {
+	if (position$1 <= 3) return .2;
+	if (position$1 > 50) return .1;
+	const distance = Math.abs(position$1 - 11);
 	return Math.max(0, 1 - distance / 15);
 }
-function calculateImpressionScore(impressions) {
-	if (impressions <= 0) return 0;
-	return Math.min(Math.log10(impressions) / 5, 1);
+function calculateImpressionScore(impressions$1) {
+	if (impressions$1 <= 0) return 0;
+	return Math.min(Math.log10(impressions$1) / 5, 1);
 }
-function calculateCtrGapScore(actualCtr, position) {
-	const expectedCtr = getExpectedCtr(position);
+function calculateCtrGapScore(actualCtr, position$1) {
+	const expectedCtr = getExpectedCtr(position$1);
 	if (actualCtr >= expectedCtr) return 0;
 	const gap = expectedCtr - actualCtr;
 	return Math.min(gap / expectedCtr, 1);
@@ -557,25 +619,25 @@ function analyzeOpportunity(keywords, options = {}) {
 	const ctrGapWeight = weights.ctrGap ?? 1;
 	const results = [];
 	for (const row of keywords) {
-		const impressions = num(row.impressions);
-		const position = num(row.position);
-		const ctr = num(row.ctr);
-		const clicks = num(row.clicks);
-		if (impressions < minImpressions) continue;
-		const positionScore = calculatePositionScore(position);
-		const impressionScore = calculateImpressionScore(impressions);
-		const ctrGapScore = calculateCtrGapScore(ctr, position);
+		const impressions$1 = num(row.impressions);
+		const position$1 = num(row.position);
+		const ctr$1 = num(row.ctr);
+		const clicks$1 = num(row.clicks);
+		if (impressions$1 < minImpressions) continue;
+		const positionScore = calculatePositionScore(position$1);
+		const impressionScore = calculateImpressionScore(impressions$1);
+		const ctrGapScore = calculateCtrGapScore(ctr$1, position$1);
 		const geometricMean = (positionScore ** positionWeight * impressionScore ** impressionsWeight * ctrGapScore ** ctrGapWeight) ** (1 / (positionWeight + impressionsWeight + ctrGapWeight));
 		const opportunityScore = Math.round(geometricMean * 100);
-		const targetCtr = getExpectedCtr(Math.min(3, position));
-		const potentialClicks = Math.round(impressions * targetCtr);
+		const targetCtr = getExpectedCtr(Math.min(3, position$1));
+		const potentialClicks = Math.round(impressions$1 * targetCtr);
 		results.push({
 			keyword: row.query,
 			page: row.page ?? null,
-			clicks,
-			impressions,
-			ctr,
-			position,
+			clicks: clicks$1,
+			impressions: impressions$1,
+			ctr: ctr$1,
+			position: position$1,
 			opportunityScore,
 			potentialClicks,
 			factors: {
@@ -657,21 +719,21 @@ function analyzeStrikingDistance(keywords, options = {}) {
 	const { minPosition = 4, maxPosition = 20, minImpressions = 100, maxCtr = .05, sortBy = "potentialClicks", sortOrder = "desc" } = options;
 	const results = [];
 	for (const row of keywords) {
-		const position = num(row.position);
-		const impressions = num(row.impressions);
-		const ctr = num(row.ctr);
-		const clicks = num(row.clicks);
-		if (position < minPosition || position > maxPosition) continue;
-		if (impressions < minImpressions) continue;
-		if (ctr > maxCtr) continue;
-		const potentialClicks = Math.round(impressions * .15);
+		const position$1 = num(row.position);
+		const impressions$1 = num(row.impressions);
+		const ctr$1 = num(row.ctr);
+		const clicks$1 = num(row.clicks);
+		if (position$1 < minPosition || position$1 > maxPosition) continue;
+		if (impressions$1 < minImpressions) continue;
+		if (ctr$1 > maxCtr) continue;
+		const potentialClicks = Math.round(impressions$1 * .15);
 		results.push({
 			keyword: row.query,
 			page: row.page ?? null,
-			clicks,
-			impressions,
-			ctr,
-			position,
+			clicks: clicks$1,
+			impressions: impressions$1,
+			ctr: ctr$1,
+			position: position$1,
 			potentialClicks
 		});
 	}

package/dist/index.d.mts

@@ -98,6 +98,7 @@ type Country = typeof Countries[keyof typeof Countries];
 //#region src/query/types.d.ts
 interface DimensionValueMap {
   query: string;
+  queryCanonical: string;
   page: string;
   country: Country;
   device: Device;
@@ -109,11 +110,18 @@ interface QueryParamValueMap {
   searchType: SearchType;
 }
 type QueryParamName = keyof QueryParamValueMap;
+declare const ColumnBrand: unique symbol;
+interface Column<D extends Dimension> {
+  readonly [ColumnBrand]: D;
+  readonly dimension: D;
+}
 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 {
-  dimension: Dimension | QueryParamName;
-  operator: FilterOperator | DateOperator;
+  dimension: Dimension | QueryParamName | Metric;
+  operator: FilterOperator | DateOperator | MetricOperator | SpecialOperator;
   expression: string;
   expression2?: string;
 }
@@ -131,17 +139,35 @@ type GSCRow<D extends Dimension[], C> = { [K in D[number]]: K extends keyof C ?
   ctr: number;
   position: number;
 };
+type Metric = 'clicks' | 'impressions' | 'ctr' | 'position';
+declare const MetricColumnBrand: unique symbol;
+interface MetricColumn<M extends Metric> {
+  readonly [MetricColumnBrand]: M;
+  readonly metric: M;
+}
 interface BuilderState {
   dimensions: Dimension[];
+  metrics?: Metric[];
   filter?: Filter<any>;
+  orderBy?: {
+    column: Metric | 'date';
+    dir: 'asc' | 'desc';
+  };
   rowLimit?: number;
   startRow?: number;
 }
 //#endregion
 //#region src/query/builder.d.ts
+type SelectableColumn = Column<Dimension> | MetricColumn<Metric>;
+type OrderableColumn = MetricColumn<Metric> | Column<'date'>;
+type ExtractDimensions<T extends SelectableColumn[]> = { [K in keyof T]: T[K] extends Column<infer D> ? D : never }[number] extends infer U ? Exclude<U, never>[] : never;
 interface GSCQueryBuilder<D extends Dimension[] = [], C = object> {
-  select: <T extends Dimension[]>(...dims: T) => GSCQueryBuilder<T, C>;
+  select: {
+    <T extends Dimension[]>(...dims: T): GSCQueryBuilder<T, C>;
+    <T extends SelectableColumn[]>(...cols: T): GSCQueryBuilder<ExtractDimensions<T> & Dimension[], C>;
+  };
   where: <F extends Filter<any>>(filter: F) => GSCQueryBuilder<D, C & F['_constraints']>;
+  orderBy: (col: OrderableColumn, dir: 'asc' | 'desc') => GSCQueryBuilder<D, C>;
   limit: (n: number) => GSCQueryBuilder<D, C>;
   offset: (n: number) => GSCQueryBuilder<D, C>;
   toBody: () => SearchAnalyticsQuery;
@@ -289,6 +315,29 @@ declare function submitSitemap(client: GoogleSearchConsoleClient, siteUrl: strin
  */
 declare function deleteSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<void>;
 //#endregion
+//#region src/core/api-client.d.ts
+interface GscdumpApiOptions {
+  /** API key (gsd_user_xxx or gsd_prod_xxx) */
+  apiKey: string;
+  /** Base URL (defaults to https://gscdump.com) */
+  baseUrl?: string;
+}
+/**
+ * Create a client that queries GSC data through gscdump.com API
+ * instead of directly to Google. Useful when you don't have OAuth credentials.
+ *
+ * @example
+ * ```ts
+ * const client = gscdumpApi({ apiKey: 'gsd_user_xxx' })
+ *
+ * // Same query builder usage as direct client
+ * for await (const rows of client.query(siteId, gsc.select('page', 'query').where(...))) {
+ *   console.log(rows)
+ * }
+ * ```
+ */
+declare function gscdumpApi(options: GscdumpApiOptions): GoogleSearchConsoleClient;
+//#endregion
 //#region src/core/errors.d.ts
 /**
  * GSC API error detection and formatting utilities.
@@ -345,4 +394,4 @@ declare function analyzeError(error: unknown): ErrorInfo;
  */
 declare function formatErrorForCli(error: unknown): string;
 //#endregion
-export { ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, DataRow, DimensionFilter, DimensionFilterGroup, ErrorInfo, GSC_QUOTAS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, IndexStatusResult, IndexingMetadata, IndexingNotificationType, IndexingResult, InspectUrlIndexResponse, InspectUrlResult, MobileUsabilityResult, Period, PublishUrlNotificationResponse, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, UrlInspectionResult, UrlNotificationMetadata, analyzeError, batchInspectUrls, batchRequestIndexing, createAuth, createFetch, deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, getErrorCode, getErrorMessage, getIndexingMetadata, getRetryAfter, googleSearchConsole, inspectUrl, isAuthError, isQuotaError, isRateLimitError, requestIndexing, submitSitemap };
+export { ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, DataRow, DimensionFilter, DimensionFilterGroup, ErrorInfo, GSC_QUOTAS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, GscdumpApiOptions, IndexStatusResult, IndexingMetadata, IndexingNotificationType, IndexingResult, InspectUrlIndexResponse, InspectUrlResult, MobileUsabilityResult, Period, PublishUrlNotificationResponse, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, UrlInspectionResult, UrlNotificationMetadata, analyzeError, batchInspectUrls, batchRequestIndexing, createAuth, createFetch, deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, getErrorCode, getErrorMessage, getIndexingMetadata, getRetryAfter, googleSearchConsole, gscdumpApi, inspectUrl, isAuthError, isQuotaError, isRateLimitError, requestIndexing, submitSitemap };

package/dist/index.mjs

@@ -130,7 +130,21 @@ const DATE_OPERATORS = [
 	"lt",
 	"between"
 ];
+const METRIC_OPERATORS = [
+	"metricGte",
+	"metricGt",
+	"metricLte",
+	"metricLt",
+	"metricBetween"
+];
+const SPECIAL_OPERATORS = ["topLevel"];
 const QUERY_PARAMS = ["searchType"];
+function isMetricOperator(op) {
+	return METRIC_OPERATORS.includes(op);
+}
+function isSpecialOperator(op) {
+	return SPECIAL_OPERATORS.includes(op);
+}
 function isDateOperator(op) {
 	return DATE_OPERATORS.includes(op);
 }
@@ -169,7 +183,8 @@ function extractSpecialFilters(filter) {
 	}
 	else if (isQueryParam(f.dimension)) {
 		if (f.dimension === "searchType") searchType = f.expression;
-	} else otherFilters.push(f);
+	} else if (isMetricOperator(f.operator) || isSpecialOperator(f.operator)) otherFilters.push(f);
+	else otherFilters.push(f);
 	if (filter._nestedGroups) for (const nested of filter._nestedGroups) {
 		const extracted = extractSpecialFilters(nested);
 		if (extracted.startDate) startDate = extracted.startDate;
@@ -204,19 +219,24 @@ function resolveToBody(state) {
 	if (filterGroups.length > 0) body.dimensionFilterGroups = filterGroups;
 	return body;
 }
+function isApiFilter(f) {
+	return !isMetricOperator(f.operator) && !isSpecialOperator(f.operator);
+}
 function resolveFilter(filter) {
 	if (!filter) return [];
 	const groups = [];
-	if ((filter._groupType ?? "and") === "or") {
-		if (filter._filters.length > 0) groups.push({
+	const groupType = filter._groupType ?? "and";
+	const apiFilters = filter._filters.filter(isApiFilter);
+	if (groupType === "or") {
+		if (apiFilters.length > 0) groups.push({
 			groupType: "or",
-			filters: filter._filters.map((f) => ({
+			filters: apiFilters.map((f) => ({
 				dimension: f.dimension,
 				operator: f.operator,
 				expression: f.expression
 			}))
 		});
-	} else if (filter._filters.length > 0) groups.push({ filters: filter._filters.map((f) => ({
+	} else if (apiFilters.length > 0) groups.push({ filters: apiFilters.map((f) => ({
 		dimension: f.dimension,
 		operator: f.operator,
 		expression: f.expression
@@ -225,6 +245,123 @@ function resolveFilter(filter) {
 	return groups;
 }
 
+//#endregion
+//#region src/core/api-client.ts
+/**
+* Create a client that queries GSC data through gscdump.com API
+* instead of directly to Google. Useful when you don't have OAuth credentials.
+*
+* @example
+* ```ts
+* const client = gscdumpApi({ apiKey: 'gsd_user_xxx' })
+*
+* // Same query builder usage as direct client
+* for await (const rows of client.query(siteId, gsc.select('page', 'query').where(...))) {
+*   console.log(rows)
+* }
+* ```
+*/
+function gscdumpApi(options) {
+	const baseUrl = options.baseUrl?.replace(/\/$/, "") || "https://gscdump.com";
+	const fetch = ofetch.create({
+		baseURL: baseUrl,
+		retry: 3,
+		retryDelay: 1e3,
+		retryStatusCodes: [
+			408,
+			429,
+			500,
+			502,
+			503,
+			504
+		],
+		headers: {
+			"x-api-key": options.apiKey,
+			"Content-Type": "application/json"
+		}
+	});
+	const rawQuery = async (siteId, body) => {
+		const response = await fetch(`/api/sites/${encodeURIComponent(siteId)}/query`, {
+			method: "POST",
+			body
+		});
+		return { rows: response.rows.map((row) => {
+			return {
+				keys: response.meta.dimensions.map((dim) => String(row[dim] ?? "")),
+				clicks: row.clicks,
+				impressions: row.impressions,
+				ctr: row.ctr,
+				position: row.position
+			};
+		}) };
+	};
+	return {
+		async *query(siteId, builder) {
+			const state = builder.getState();
+			const body = resolveToBody(state);
+			const rowLimit = body.rowLimit || 25e3;
+			let startRow = body.startRow || 0;
+			while (true) {
+				const response = await fetch(`/api/sites/${encodeURIComponent(siteId)}/query`, {
+					method: "POST",
+					body: {
+						...body,
+						startRow,
+						rowLimit
+					}
+				});
+				const rows = response.rows.map((row) => {
+					const result = {
+						clicks: row.clicks ?? 0,
+						impressions: row.impressions ?? 0,
+						ctr: row.ctr ?? 0,
+						position: row.position ?? 0
+					};
+					state.dimensions.forEach((dim) => {
+						result[dim] = row[dim];
+					});
+					return result;
+				});
+				yield rows;
+				if (!response.meta.hasMore || rows.length < rowLimit) break;
+				startRow += rows.length;
+			}
+		},
+		sites: async () => {
+			return (await fetch("/api/sites")).sites.map((s) => ({
+				siteUrl: s.gscSiteUrl,
+				permissionLevel: s.permissionLevel || "siteOwner"
+			}));
+		},
+		inspect: () => {
+			throw new Error("URL inspection not available via gscdump API. Use googleSearchConsole() with OAuth credentials.");
+		},
+		sitemaps: {
+			list: async (siteId) => {
+				return (await fetch(`/api/sites/${encodeURIComponent(siteId)}/sitemaps`)).sitemaps || [];
+			},
+			get: () => {
+				throw new Error("Sitemap get not available via gscdump API.");
+			},
+			submit: () => {
+				throw new Error("Sitemap submit not available via gscdump API.");
+			},
+			delete: () => {
+				throw new Error("Sitemap delete not available via gscdump API.");
+			}
+		},
+		indexing: {
+			publish: () => {
+				throw new Error("Indexing API not available via gscdump API. Use googleSearchConsole() with OAuth credentials.");
+			},
+			getMetadata: () => {
+				throw new Error("Indexing API not available via gscdump API. Use googleSearchConsole() with OAuth credentials.");
+			}
+		},
+		_rawQuery: rawQuery
+	};
+}
+
 //#endregion
 //#region src/core/client.ts
 const GSC_API = "https://searchconsole.googleapis.com";
@@ -527,4 +664,4 @@ function formatErrorForCli(error) {
 }
 
 //#endregion
-export { GSC_QUOTAS, analyzeError, batchInspectUrls, batchRequestIndexing, createAuth, createFetch, deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, getErrorCode, getErrorMessage, getIndexingMetadata, getRetryAfter, googleSearchConsole, inspectUrl, isAuthError, isQuotaError, isRateLimitError, requestIndexing, submitSitemap };
+export { GSC_QUOTAS, analyzeError, batchInspectUrls, batchRequestIndexing, createAuth, createFetch, deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, getErrorCode, getErrorMessage, getIndexingMetadata, getRetryAfter, googleSearchConsole, gscdumpApi, inspectUrl, isAuthError, isQuotaError, isRateLimitError, requestIndexing, submitSitemap };

package/dist/query/index.d.mts

@@ -33,6 +33,7 @@ type Country = typeof Countries[keyof typeof Countries];
 //#region src/query/types.d.ts
 interface DimensionValueMap {
   query: string;
+  queryCanonical: string;
   page: string;
   country: Country;
   device: Device;
@@ -56,9 +57,11 @@ interface QueryParam<P extends QueryParamName> {
 }
 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 {
-  dimension: Dimension | QueryParamName;
-  operator: FilterOperator | DateOperator;
+  dimension: Dimension | QueryParamName | Metric;
+  operator: FilterOperator | DateOperator | MetricOperator | SpecialOperator;
   expression: string;
   expression2?: string;
 }
@@ -71,7 +74,7 @@ interface Filter<C = object> {
   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;
+type UnionToIntersection<U$1> = (U$1 extends any ? (k: U$1) => void : never) extends ((k: infer I) => void) ? I : never;
 interface GSCResult<D extends Dimension[], C> {
   rows: Array<GSCRow<D, C>>;
 }
@@ -81,17 +84,35 @@ type GSCRow<D extends Dimension[], C> = { [K in D[number]]: K extends keyof C ?
   ctr: number;
   position: number;
 };
+type Metric = 'clicks' | 'impressions' | 'ctr' | 'position';
+declare const MetricColumnBrand: unique symbol;
+interface MetricColumn<M extends Metric> {
+  readonly [MetricColumnBrand]: M;
+  readonly metric: M;
+}
 interface BuilderState {
   dimensions: Dimension[];
+  metrics?: Metric[];
   filter?: Filter<any>;
+  orderBy?: {
+    column: Metric | 'date';
+    dir: 'asc' | 'desc';
+  };
   rowLimit?: number;
   startRow?: number;
 }
 //#endregion
 //#region src/query/builder.d.ts
+type SelectableColumn = Column<Dimension> | MetricColumn<Metric>;
+type OrderableColumn = MetricColumn<Metric> | Column<'date'>;
+type ExtractDimensions<T extends SelectableColumn[]> = { [K in keyof T]: T[K] extends Column<infer D> ? D : never }[number] extends infer U ? Exclude<U, never>[] : never;
 interface GSCQueryBuilder<D extends Dimension[] = [], C = object> {
-  select: <T extends Dimension[]>(...dims: T) => GSCQueryBuilder<T, C>;
+  select: {
+    <T extends Dimension[]>(...dims: T): GSCQueryBuilder<T, C>;
+    <T extends SelectableColumn[]>(...cols: T): GSCQueryBuilder<ExtractDimensions<T> & Dimension[], C>;
+  };
   where: <F extends Filter<any>>(filter: F) => GSCQueryBuilder<D, C & F['_constraints']>;
+  orderBy: (col: OrderableColumn, dir: 'asc' | 'desc') => GSCQueryBuilder<D, C>;
   limit: (n: number) => GSCQueryBuilder<D, C>;
   offset: (n: number) => GSCQueryBuilder<D, C>;
   toBody: () => SearchAnalyticsQuery;
@@ -102,10 +123,15 @@ declare const gsc: GSCQueryBuilder<[], object>;
 //#region src/query/columns.d.ts
 declare const page: Column<"page">;
 declare const query: Column<"query">;
+declare const queryCanonical: Column<"queryCanonical">;
 declare const device: Column<"device">;
 declare const country: Column<"country">;
 declare const searchAppearance: Column<"searchAppearance">;
 declare const date: Column<"date">;
+declare const clicks: MetricColumn<"clicks">;
+declare const impressions: MetricColumn<"impressions">;
+declare const ctr: MetricColumn<"ctr">;
+declare const position: MetricColumn<"position">;
 declare const searchType: QueryParam<"searchType">;
 //#endregion
 //#region src/query/operators.d.ts
@@ -120,17 +146,25 @@ declare function notRegex<D extends Dimension>(column: Column<D>, pattern: RegEx
 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<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
+declare function gt<M extends Metric>(column: MetricColumn<M>, value: number): Filter<object>;
 declare function gt<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
+declare function lte<M extends Metric>(column: MetricColumn<M>, value: number): Filter<object>;
 declare function lte<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
+declare function lt<M extends Metric>(column: MetricColumn<M>, value: number): Filter<object>;
 declare function lt<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
+declare function between<M extends Metric>(column: MetricColumn<M>, start: number, end: number): Filter<object>;
 declare function between<D extends Dimension>(column: Column<D>, start: DimensionValueMap[D], end: DimensionValueMap[D]): Filter<object>;
+declare function topLevel(column: Column<'page'>): Filter<object>;
 //#endregion
 //#region src/query/resolver.d.ts
 declare function extractDateRange(filter?: Filter<any>): {
   startDate?: string;
   endDate?: string;
 };
+declare function extractMetricFilters(filter?: Filter<any>): InternalFilter[];
+declare function extractSpecialOperatorFilters(filter?: Filter<any>): InternalFilter[];
 //#endregion
 //#region src/query/utils/dayjs.d.ts
 declare function dayjs(date?: _dayjs.ConfigType): Dayjs;
@@ -141,4 +175,4 @@ declare function dayjsPst(): Dayjs;
 declare function today(): string;
 declare function daysAgo(n: number): string;
 //#endregion
-export { type BuilderState, type Column, Countries, type Country, type Device, Devices, type Dimension, type DimensionValueMap, type Filter, type GSCQueryBuilder, type GSCResult, type GSCRow, type QueryParam, type QueryParamName, type QueryParamValueMap, type SearchType, SearchTypes, and, between, contains, country, currentPstDate, date, dayjs, dayjsPst, daysAgo, device, eq, extractDateRange, gsc, gt, gte, inArray, like, lt, lte, ne, not, notRegex, or, page, query, regex, searchAppearance, searchType, today };
+export { type BuilderState, type Column, Countries, type Country, type Device, Devices, type Dimension, type DimensionValueMap, type Filter, type GSCQueryBuilder, type GSCResult, type GSCRow, type InternalFilter, type Metric, type MetricColumn, type QueryParam, type QueryParamName, type QueryParamValueMap, type SearchType, SearchTypes, and, between, clicks, contains, country, ctr, currentPstDate, date, dayjs, dayjsPst, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSpecialOperatorFilters, gsc, gt, gte, impressions, inArray, like, lt, lte, ne, not, notRegex, or, page, position, query, queryCanonical, regex, searchAppearance, searchType, today, topLevel };

package/dist/query/index.mjs

@@ -24,7 +24,21 @@ const DATE_OPERATORS = [
 	"lt",
 	"between"
 ];
+const METRIC_OPERATORS = [
+	"metricGte",
+	"metricGt",
+	"metricLte",
+	"metricLt",
+	"metricBetween"
+];
+const SPECIAL_OPERATORS = ["topLevel"];
 const QUERY_PARAMS = ["searchType"];
+function isMetricOperator(op) {
+	return METRIC_OPERATORS.includes(op);
+}
+function isSpecialOperator(op) {
+	return SPECIAL_OPERATORS.includes(op);
+}
 function isDateOperator(op) {
 	return DATE_OPERATORS.includes(op);
 }
@@ -63,7 +77,8 @@ function extractSpecialFilters(filter) {
 	}
 	else if (isQueryParam(f.dimension)) {
 		if (f.dimension === "searchType") searchType$1 = f.expression;
-	} else otherFilters.push(f);
+	} else if (isMetricOperator(f.operator) || isSpecialOperator(f.operator)) otherFilters.push(f);
+	else otherFilters.push(f);
 	if (filter._nestedGroups) for (const nested of filter._nestedGroups) {
 		const extracted = extractSpecialFilters(nested);
 		if (extracted.startDate) startDate = extracted.startDate;
@@ -90,6 +105,18 @@ function extractDateRange(filter) {
 		endDate
 	};
 }
+function extractMetricFilters(filter) {
+	if (!filter) return [];
+	const metricFilters = filter._filters.filter((f) => isMetricOperator(f.operator));
+	const nested = filter._nestedGroups?.flatMap((g) => extractMetricFilters(g)) ?? [];
+	return [...metricFilters, ...nested];
+}
+function extractSpecialOperatorFilters(filter) {
+	if (!filter) return [];
+	const special = filter._filters.filter((f) => isSpecialOperator(f.operator));
+	const nested = filter._nestedGroups?.flatMap((g) => extractSpecialOperatorFilters(g)) ?? [];
+	return [...special, ...nested];
+}
 function resolveToBody(state) {
 	const { startDate, endDate, searchType: searchType$1, 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)))");
@@ -105,19 +132,24 @@ function resolveToBody(state) {
 	if (filterGroups.length > 0) body.dimensionFilterGroups = filterGroups;
 	return body;
 }
+function isApiFilter(f) {
+	return !isMetricOperator(f.operator) && !isSpecialOperator(f.operator);
+}
 function resolveFilter(filter) {
 	if (!filter) return [];
 	const groups = [];
-	if ((filter._groupType ?? "and") === "or") {
-		if (filter._filters.length > 0) groups.push({
+	const groupType = filter._groupType ?? "and";
+	const apiFilters = filter._filters.filter(isApiFilter);
+	if (groupType === "or") {
+		if (apiFilters.length > 0) groups.push({
 			groupType: "or",
-			filters: filter._filters.map((f) => ({
+			filters: apiFilters.map((f) => ({
 				dimension: f.dimension,
 				operator: f.operator,
 				expression: f.expression
 			}))
 		});
-	} else if (filter._filters.length > 0) groups.push({ filters: filter._filters.map((f) => ({
+	} else if (apiFilters.length > 0) groups.push({ filters: apiFilters.map((f) => ({
 		dimension: f.dimension,
 		operator: f.operator,
 		expression: f.expression
@@ -128,12 +160,27 @@ function resolveFilter(filter) {
 
 //#endregion
 //#region src/query/builder.ts
+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(...dims) {
+		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: dims
+				dimensions,
+				metrics: metrics.length > 0 ? metrics : void 0
 			});
 		},
 		where(filter) {
@@ -142,6 +189,16 @@ function createBuilder(state) {
 				filter
 			});
 		},
+		orderBy(col, dir) {
+			const column = isMetricColumn(col) ? col.metric : col.dimension;
+			return createBuilder({
+				...state,
+				orderBy: {
+					column,
+					dir
+				}
+			});
+		},
 		limit(n) {
 			return createBuilder({
 				...state,
@@ -169,15 +226,23 @@ 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 clicks = createMetricColumn("clicks");
+const impressions = createMetricColumn("impressions");
+const ctr = createMetricColumn("ctr");
+const position = createMetricColumn("position");
 const searchType = createQueryParam("searchType");
 
 //#endregion
@@ -1816,6 +1881,14 @@ function invertOperator(op) {
 	}[op];
 }
 function gte(column, value) {
+	if ("metric" in column) return {
+		_constraints: {},
+		_filters: [{
+			dimension: column.metric,
+			operator: "metricGte",
+			expression: String(value)
+		}]
+	};
 	return {
 		_constraints: {},
 		_filters: [{
@@ -1826,6 +1899,14 @@ function gte(column, value) {
 	};
 }
 function gt(column, value) {
+	if ("metric" in column) return {
+		_constraints: {},
+		_filters: [{
+			dimension: column.metric,
+			operator: "metricGt",
+			expression: String(value)
+		}]
+	};
 	return {
 		_constraints: {},
 		_filters: [{
@@ -1836,6 +1917,14 @@ function gt(column, value) {
 	};
 }
 function lte(column, value) {
+	if ("metric" in column) return {
+		_constraints: {},
+		_filters: [{
+			dimension: column.metric,
+			operator: "metricLte",
+			expression: String(value)
+		}]
+	};
 	return {
 		_constraints: {},
 		_filters: [{
@@ -1846,6 +1935,14 @@ function lte(column, value) {
 	};
 }
 function lt(column, value) {
+	if ("metric" in column) return {
+		_constraints: {},
+		_filters: [{
+			dimension: column.metric,
+			operator: "metricLt",
+			expression: String(value)
+		}]
+	};
 	return {
 		_constraints: {},
 		_filters: [{
@@ -1856,6 +1953,15 @@ function lt(column, value) {
 	};
 }
 function between(column, start, end) {
+	if ("metric" in column) return {
+		_constraints: {},
+		_filters: [{
+			dimension: column.metric,
+			operator: "metricBetween",
+			expression: String(start),
+			expression2: String(end)
+		}]
+	};
 	return {
 		_constraints: {},
 		_filters: [{
@@ -1866,6 +1972,16 @@ function between(column, start, end) {
 		}]
 	};
 }
+function topLevel(column) {
+	return {
+		_constraints: {},
+		_filters: [{
+			dimension: column.dimension,
+			operator: "topLevel",
+			expression: ""
+		}]
+	};
+}
 
 //#endregion
 //#region src/query/index.ts
@@ -1877,4 +1993,4 @@ function daysAgo(n) {
 }
 
 //#endregion
-export { Countries, Devices, SearchTypes, and, between, contains, country, currentPstDate, date, dayjs, dayjsPst, daysAgo, device, eq, extractDateRange, gsc, gt, gte, inArray, like, lt, lte, ne, not, notRegex, or, page, query, regex, searchAppearance, searchType, today };
+export { Countries, Devices, SearchTypes, and, between, clicks, contains, country, ctr, currentPstDate, date, dayjs, dayjsPst, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSpecialOperatorFilters, gsc, gt, gte, impressions, inArray, like, lt, lte, ne, not, notRegex, or, page, position, query, queryCanonical, regex, searchAppearance, searchType, today, topLevel };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gscdump",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Google Search Console API wrapper with typed query builder, streaming pagination, and SEO analysis functions",
   "author": {
     "name": "Harlan Wilton",