@gscdump/engine-gsc-api 4.2.3 → 4.3.0

package/dist/index.d.mts

@@ -2,5 +2,5 @@ import { CreateLiveGscSourceOptions, canProxyToGsc, createLiveGscSource } from "
 import { FetchTopNOptions, GscDailyRow, GscRange, GscTopNRow, fetchGscDaily, fetchGscTopN } from "./rollup-synth.mjs";
 import { GSC_API_CAPABILITIES, GscApiQuerySourceOptions, createGscApiQuerySource } from "./source.mjs";
 import { GscSyncEntryWork, GscSyncFanoutEntry, GscSyncLedgerRow, GscSyncWindow, GscSyncWorkPlan, PlanGscBackfillDatesOptions, PlanGscBackwardDatesOptions, PlanGscSyncWorkOptions, gscSyncFanout, ledgerTablesForGscSync, planGscBackfillDates, planGscSyncWork, tablesCoveredByGscSync } from "./sync-plan.mjs";
-import { GscApiRow, RunGscSearchAppearanceContextSliceOptions, RunGscSearchAppearanceContextSliceResult, RunGscSyncSliceOptions, RunGscSyncSliceResult, SearchAppearanceContextGrain, SearchAppearanceContextTable, SyncSliceDimensionFilter, SyncSliceDomainFilter, runGscSearchAppearanceContextSlice, runGscSyncSlice } from "./sync-slice.mjs";
-export { type CreateLiveGscSourceOptions, type FetchTopNOptions, GSC_API_CAPABILITIES, type GscApiQuerySourceOptions, type GscApiRow, type GscDailyRow, type GscRange, type GscSyncEntryWork, type GscSyncFanoutEntry, type GscSyncLedgerRow, type GscSyncWindow, type GscSyncWorkPlan, type GscTopNRow, type PlanGscBackfillDatesOptions, type PlanGscBackwardDatesOptions, type PlanGscSyncWorkOptions, type RunGscSearchAppearanceContextSliceOptions, type RunGscSearchAppearanceContextSliceResult, type RunGscSyncSliceOptions, type RunGscSyncSliceResult, type SearchAppearanceContextGrain, type SearchAppearanceContextTable, type SyncSliceDimensionFilter, type SyncSliceDomainFilter, canProxyToGsc, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN, gscSyncFanout, ledgerTablesForGscSync, planGscBackfillDates, planGscSyncWork, runGscSearchAppearanceContextSlice, runGscSyncSlice, tablesCoveredByGscSync };
+import { GscAggregation, GscApiRow, RunGscSearchAppearanceContextSliceOptions, RunGscSearchAppearanceContextSliceResult, RunGscSyncSliceOptions, RunGscSyncSliceResult, SearchAppearanceContextGrain, SearchAppearanceContextTable, SyncSliceDimensionFilter, SyncSliceDomainFilter, hostPagePattern, requestAggregation, runGscSearchAppearanceContextSlice, runGscSyncSlice } from "./sync-slice.mjs";
+export { type CreateLiveGscSourceOptions, type FetchTopNOptions, GSC_API_CAPABILITIES, type GscAggregation, type GscApiQuerySourceOptions, type GscApiRow, type GscDailyRow, type GscRange, type GscSyncEntryWork, type GscSyncFanoutEntry, type GscSyncLedgerRow, type GscSyncWindow, type GscSyncWorkPlan, type GscTopNRow, type PlanGscBackfillDatesOptions, type PlanGscBackwardDatesOptions, type PlanGscSyncWorkOptions, type RunGscSearchAppearanceContextSliceOptions, type RunGscSearchAppearanceContextSliceResult, type RunGscSyncSliceOptions, type RunGscSyncSliceResult, type SearchAppearanceContextGrain, type SearchAppearanceContextTable, type SyncSliceDimensionFilter, type SyncSliceDomainFilter, canProxyToGsc, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN, gscSyncFanout, hostPagePattern, ledgerTablesForGscSync, planGscBackfillDates, planGscSyncWork, requestAggregation, runGscSearchAppearanceContextSlice, runGscSyncSlice, tablesCoveredByGscSync };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { fetchGscDaily, fetchGscTopN } from "./rollup-synth.mjs";
 import { GSC_API_CAPABILITIES, createGscApiQuerySource } from "./source.mjs";
+import { hostPagePattern, requestAggregation, runGscSearchAppearanceContextSlice, runGscSyncSlice } from "./sync-slice.mjs";
 import { canProxyToGsc, createLiveGscSource } from "./live.mjs";
 import { gscSyncFanout, ledgerTablesForGscSync, planGscBackfillDates, planGscSyncWork, tablesCoveredByGscSync } from "./sync-plan.mjs";
-import { runGscSearchAppearanceContextSlice, runGscSyncSlice } from "./sync-slice.mjs";
-export { GSC_API_CAPABILITIES, canProxyToGsc, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN, gscSyncFanout, ledgerTablesForGscSync, planGscBackfillDates, planGscSyncWork, runGscSearchAppearanceContextSlice, runGscSyncSlice, tablesCoveredByGscSync };
+export { GSC_API_CAPABILITIES, canProxyToGsc, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN, gscSyncFanout, hostPagePattern, ledgerTablesForGscSync, planGscBackfillDates, planGscSyncWork, requestAggregation, runGscSearchAppearanceContextSlice, runGscSyncSlice, tablesCoveredByGscSync };

package/dist/live.d.mts

@@ -20,5 +20,13 @@ export interface CreateLiveGscSourceOptions {
    * slice only. An explicit search type already present on the state wins.
    */
   searchType?: SearchType$1;
+  /**
+   * Scope every read to one exact host with the same `page` filter the sync
+   * applies. Set it whenever the sync filters, so live and stored rows count
+   * impressions the same way.
+   */
+  pageScope?: {
+    host: string;
+  };
 }
 export declare function createLiveGscSource(opts: CreateLiveGscSourceOptions): AnalysisQuerySource;

package/dist/live.mjs

@@ -1,6 +1,7 @@
 import { createGscApiQuerySource } from "./source.mjs";
+import { hostPagePattern } from "./sync-slice.mjs";
 import { googleSearchConsole } from "gscdump";
-import { normalizeBuilderStateResult } from "gscdump/query";
+import { and, normalizeBuilderStateResult, page, queryErrorToException, queryErrors, regex } from "gscdump/query";
 const PRO_ONLY_DIMENSIONS = /* @__PURE__ */ new Set(["queryCanonical", "page_keywords"]);
 function hasMatchingFilter(filter, matches) {
 	return !!filter && (filter._filters.some((leaf) => matches(leaf.dimension)) || (filter._nestedGroups ?? []).some((group) => hasMatchingFilter(group, matches)));
@@ -17,6 +18,18 @@ function withSearchType(state, searchType) {
 		searchType
 	};
 }
+function withPageScope(state, host) {
+	const parsed = normalizeBuilderStateResult(state);
+	if (!parsed.ok) throw queryErrorToException(parsed.error);
+	const base = parsed.value;
+	if (base.aggregationType === "byProperty") throw queryErrorToException(queryErrors.byPropertyNotAllowedWithPage());
+	if (base.aggregationType === "byNewsShowcasePanel") throw queryErrorToException(queryErrors.byNewsShowcaseNotAllowedWithPage());
+	const scope = regex(page, hostPagePattern(host));
+	return {
+		...base,
+		filter: base.filter ? and(base.filter, scope) : scope
+	};
+}
 function createLiveGscSource(opts) {
 	let clientPromise = null;
 	function getClient() {
@@ -37,7 +50,8 @@ function createLiveGscSource(opts) {
 		},
 		async queryRows(state) {
 			const client = await getClient();
-			const scopedState = opts.searchType !== void 0 ? withSearchType(state, opts.searchType) : state;
+			const typed = opts.searchType !== void 0 ? withSearchType(state, opts.searchType) : state;
+			const scopedState = opts.pageScope ? withPageScope(typed, opts.pageScope.host) : typed;
 			return createGscApiQuerySource({
 				client,
 				siteUrl: opts.siteUrl

package/dist/sync-slice.d.mts

@@ -68,10 +68,18 @@ export interface RunGscSyncSliceOptions {
     rowsThisPage: number;
   }) => void;
 }
+/**
+ * How GSC counted impressions for a request. Grouping or filtering by `page`
+ * counts one impression per ranking URL (`byPage`). Anything else counts one
+ * per search result (`byProperty`), which is what the Search Console UI shows.
+ */
+export type GscAggregation = 'byPage' | 'byProperty';
 export interface RunGscSyncSliceResult {
   totalRows: number;
   hasMore: boolean;
   nextStartRow: number;
+  /** How GSC counted impressions for every row this slice wrote. */
+  aggregation: GscAggregation;
   /**
    * Metadata from the LAST GSC API page seen during this slice run. When
    *  `dataState='hourly_all'` and grouped by `hour`, this surfaces
@@ -123,6 +131,8 @@ export type SearchAppearanceContinuation = {
 export interface RunGscSearchAppearanceContextSliceResult {
   appearances: string[];
   totalRows: number;
+  /** How GSC counted impressions for each table this run wrote rows to. */
+  aggregation: Partial<Record<'search_appearance' | SearchAppearanceContextTable, GscAggregation>>;
   hasMore: boolean;
   continuation?: SearchAppearanceContinuation;
   /**
@@ -133,6 +143,18 @@ export interface RunGscSearchAppearanceContextSliceResult {
    */
   metadata?: GscSearchAnalyticsMetadata;
 }
+/** The `page` regex that scopes a request to one exact host. */
+export declare function hostPagePattern(host: string): string;
+/**
+ * The counting GSC should apply to a request with these dimensions, filters,
+ * and search type. The sync prefers the `responseAggregationType` GSC reports;
+ * this is the fallback when a response omits it.
+ */
+export declare function requestAggregation(dimensions: readonly string[], filterGroups: readonly {
+  filters: readonly {
+    dimension: string;
+  }[];
+}[] | undefined, searchType?: SearchType): GscAggregation;
 export declare function runGscSyncSlice(opts: RunGscSyncSliceOptions): Promise<RunGscSyncSliceResult>;
 /**
  * Implements GSC's required two-step search-appearance flow:

package/dist/sync-slice.mjs

@@ -22,20 +22,27 @@ function isTimeoutLike(err) {
 	if (!(err instanceof Error)) return false;
 	return err.name === "AbortError" || err.message?.includes("timeout") || err.message?.includes("aborted");
 }
+function hostPagePattern(host) {
+	return `^https?://${host.replace(/\./g, "\\.")}/`;
+}
+function requestAggregation(dimensions, filterGroups, searchType = "web") {
+	if (searchType === "discover" || searchType === "googleNews") return "byPage";
+	return dimensions.includes("page") || (filterGroups ?? []).some((group) => group.filters.some((filter) => filter.dimension === "page")) ? "byPage" : "byProperty";
+}
+function reportedAggregation(value) {
+	return value === "byPage" || value === "byProperty" ? value : null;
+}
 function buildDimensionFilterGroups(domainFilter, filters = []) {
 	const out = filters.map((f) => ({
 		dimension: f.dimension,
 		operator: f.operator ?? "equals",
 		expression: f.expression
 	}));
-	if (domainFilter?.domain) {
-		const pattern = `^https?://${domainFilter.domain.replace(/\./g, "\\.")}/`;
-		out.push({
-			dimension: "page",
-			operator: "includingRegex",
-			expression: pattern
-		});
-	}
+	if (domainFilter?.domain) out.push({
+		dimension: "page",
+		operator: "includingRegex",
+		expression: hostPagePattern(domainFilter.domain)
+	});
 	return out.length > 0 ? [{ filters: out }] : void 0;
 }
 async function runGscSyncSlice(opts) {
@@ -46,6 +53,7 @@ async function runGscSyncSlice(opts) {
 	const dimensions = opts.dimensions ? [...opts.dimensions] : [...DIMENSIONS_BY_TABLE[opts.table]];
 	const dataState = opts.dataState ?? (dimensions.includes("hour") ? "hourly_all" : "all");
 	const dimensionFilterGroups = buildDimensionFilterGroups(opts.domainFilter, opts.dimensionFilters);
+	let aggregation = requestAggregation(dimensions, dimensionFilterGroups, searchType);
 	const loopStart = Date.now();
 	let startRow = opts.initialStartRow ?? 0;
 	let totalRows = 0;
@@ -67,6 +75,7 @@ async function runGscSyncSlice(opts) {
 			return {
 				kind: "ok",
 				startRow: row,
+				reported: reportedAggregation(response.responseAggregationType),
 				rows: response.rows ?? [],
 				metadata: response.metadata
 			};
@@ -91,7 +100,8 @@ async function runGscSyncSlice(opts) {
 		totalRows,
 		hasMore: true,
 		nextStartRow: startRow,
-		metadata
+		metadata,
+		aggregation
 	};
 	while (pending !== null) {
 		const page = await pending;
@@ -101,12 +111,14 @@ async function runGscSyncSlice(opts) {
 			totalRows,
 			hasMore: true,
 			nextStartRow: page.startRow,
-			metadata
+			metadata,
+			aggregation
 		};
 		const rows = page.rows;
 		totalRows += rows.length;
 		pageCount++;
 		if (page.metadata) metadata = page.metadata;
+		aggregation = page.reported ?? aggregation;
 		opts.onPage?.({
 			searchType,
 			rowsThisPage: rows.length
@@ -122,20 +134,23 @@ async function runGscSyncSlice(opts) {
 				totalRows: totalRows - rows.length,
 				hasMore: true,
 				nextStartRow: page.startRow,
-				metadata
+				metadata,
+				aggregation
 			};
 		}
 		if (isLastPage) return {
 			totalRows,
 			hasMore: false,
 			nextStartRow,
-			metadata
+			metadata,
+			aggregation
 		};
 		if (prefetch === null) return {
 			totalRows,
 			hasMore: true,
 			nextStartRow,
-			metadata
+			metadata,
+			aggregation
 		};
 		startRow = nextStartRow;
 		pending = prefetch;
@@ -144,7 +159,8 @@ async function runGscSyncSlice(opts) {
 		totalRows,
 		hasMore: false,
 		nextStartRow: startRow,
-		metadata
+		metadata,
+		aggregation
 	};
 }
 function contextTableForGrain(grain) {
@@ -160,6 +176,7 @@ async function runGscSearchAppearanceContextSlice(opts) {
 	let totalRows = 0;
 	let hasMore = false;
 	let metadata;
+	const aggregation = {};
 	if (!opts.appearances && opts.continuation?.phase !== "context") {
 		const discovered = new Set(appearances);
 		const discovery = await runGscSyncSlice({
@@ -186,9 +203,11 @@ async function runGscSearchAppearanceContextSlice(opts) {
 		});
 		totalRows += discovery.totalRows;
 		metadata = discovery.metadata;
+		aggregation.search_appearance = discovery.aggregation;
 		if (discovery.hasMore) return {
 			appearances: [...discovered],
 			totalRows,
+			aggregation,
 			hasMore: true,
 			continuation: {
 				phase: "discovery",
@@ -230,9 +249,11 @@ async function runGscSearchAppearanceContextSlice(opts) {
 		});
 		totalRows += context.totalRows;
 		metadata = context.metadata;
+		aggregation[table] = context.aggregation;
 		if (context.hasMore) return {
 			appearances,
 			totalRows,
+			aggregation,
 			hasMore: true,
 			continuation: {
 				phase: "context",
@@ -248,7 +269,8 @@ async function runGscSearchAppearanceContextSlice(opts) {
 		appearances,
 		totalRows,
 		hasMore,
-		metadata
+		metadata,
+		aggregation
 	};
 }
-export { runGscSearchAppearanceContextSlice, runGscSyncSlice };
+export { hostPagePattern, requestAggregation, runGscSearchAppearanceContextSlice, runGscSyncSlice };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine-gsc-api",
   "type": "module",
-  "version": "4.2.3",
+  "version": "4.3.0",
   "description": "GSC live-API engine adapter — wraps the Search Analytics REST API as an AnalysisQuerySource for typed analyzer dispatch.",
   "author": {
     "name": "Harlan Wilton",
@@ -36,8 +36,8 @@
     "node": ">=22.13.0"
   },
   "dependencies": {
-    "@gscdump/engine": "^4.2.3",
-    "gscdump": "^4.2.3"
+    "@gscdump/engine": "^4.3.0",
+    "gscdump": "^4.3.0"
   },
   "devDependencies": {
     "vitest": "^5.0.1"