@gscdump/engine-gsc-api 0.21.3 → 0.22.1

package/dist/index.d.mts

@@ -82,14 +82,21 @@ interface SyncSliceDomainFilter {
    */
   domain?: string;
 }
+interface SyncSliceDimensionFilter {
+  dimension: 'page' | 'query' | 'country' | 'device' | 'searchAppearance';
+  operator?: 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
+  expression: string;
+}
 interface RunGscSyncSliceOptions {
   client: GoogleSearchConsoleClient;
   siteUrl: string;
   /** One of the engine sync-fan tables. Drives the dimension list. */
-  table: 'pages' | 'queries' | 'countries' | 'dates' | 'page_queries' | 'hourly_pages';
+  table: 'pages' | 'queries' | 'countries' | 'dates' | 'page_queries' | 'search_appearance' | 'search_appearance_pages' | 'search_appearance_queries' | 'search_appearance_page_queries' | 'hourly_pages';
   startDate: string;
   endDate: string;
   domainFilter?: SyncSliceDomainFilter | null;
+  /** Additional AND filters, e.g. `searchAppearance = AMP_BLUE_LINK`. */
+  dimensionFilters?: SyncSliceDimensionFilter[];
   /**
    * Override the dimension list for this slice. Defaults to
    *  `DIMENSIONS_BY_TABLE[table]`. Hosts that need bespoke groupings (e.g.
@@ -139,5 +146,46 @@ interface RunGscSyncSliceResult {
    */
   metadata?: GscSearchAnalyticsMetadata;
 }
+type SearchAppearanceContextGrain = 'page' | 'query' | 'page_query';
+type SearchAppearanceContextTable = 'search_appearance_pages' | 'search_appearance_queries' | 'search_appearance_page_queries';
+interface RunGscSearchAppearanceContextSliceOptions {
+  client: GoogleSearchConsoleClient;
+  siteUrl: string;
+  startDate: string;
+  endDate: string;
+  domainFilter?: SyncSliceDomainFilter | null;
+  /** Use a known appearance list to skip discovery. */
+  appearances?: string[];
+  /** Context grain to fetch for every discovered appearance. Defaults to page_query. */
+  grain?: SearchAppearanceContextGrain;
+  /** Context table to fetch. Overrides `grain` when provided. */
+  table?: SearchAppearanceContextTable;
+  dataState?: GscDataState;
+  rowLimit?: number;
+  maxPages?: number;
+  cpuBudgetMs?: number;
+  searchType?: SearchType$1;
+  onTotalBatch?: (rows: GscApiRow[]) => Promise<void>;
+  onContextBatch: (batch: {
+    searchAppearance: string;
+    table: SearchAppearanceContextTable;
+    rows: GscApiRow[];
+  }) => Promise<void>;
+  onPage?: (info: {
+    searchType: SearchType$1;
+    rowsThisPage: number;
+  }) => void;
+}
+interface RunGscSearchAppearanceContextSliceResult {
+  appearances: string[];
+  totalRows: number;
+  hasMore: boolean;
+}
 declare function runGscSyncSlice(opts: RunGscSyncSliceOptions): Promise<RunGscSyncSliceResult>;
-export { type CreateLiveGscSourceOptions, type FetchTopNOptions, type GscApiQuerySourceOptions, type GscApiRow, type GscDailyRow, type GscRange, type GscTopNRow, type RunGscSyncSliceOptions, type RunGscSyncSliceResult, type SyncSliceDomainFilter, canProxyToGsc, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN, runGscSyncSlice };
+/**
+ * Implements GSC's required two-step search-appearance flow:
+ * 1. group by `searchAppearance` alone to discover available appearances;
+ * 2. for each appearance, filter by it and fetch page/query/date context.
+ */
+declare function runGscSearchAppearanceContextSlice(opts: RunGscSearchAppearanceContextSliceOptions): Promise<RunGscSearchAppearanceContextSliceResult>;
+export { type CreateLiveGscSourceOptions, type FetchTopNOptions, type GscApiQuerySourceOptions, type GscApiRow, type GscDailyRow, type GscRange, type GscTopNRow, type RunGscSearchAppearanceContextSliceOptions, type RunGscSearchAppearanceContextSliceResult, type RunGscSyncSliceOptions, type RunGscSyncSliceResult, type SearchAppearanceContextGrain, type SearchAppearanceContextTable, type SyncSliceDimensionFilter, type SyncSliceDomainFilter, canProxyToGsc, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN, runGscSearchAppearanceContextSlice, runGscSyncSlice };

package/dist/index.mjs

@@ -172,19 +172,35 @@ const DIMENSIONS_BY_TABLE = {
 		"query",
 		"date"
 	],
+	search_appearance: ["searchAppearance"],
+	search_appearance_pages: ["page", "date"],
+	search_appearance_queries: ["query", "date"],
+	search_appearance_page_queries: [
+		"page",
+		"query",
+		"date"
+	],
 	hourly_pages: ["hour", "page"]
 };
 function isTimeoutLike(err) {
 	if (!(err instanceof Error)) return false;
 	return err.name === "AbortError" || err.message?.includes("timeout") || err.message?.includes("aborted");
 }
-function buildDomainFilterGroups(filter) {
-	if (!filter?.domain) return void 0;
-	return [{ filters: [{
-		dimension: "page",
-		operator: "includingRegex",
-		expression: `^https?://(www\\.)?${filter.domain.replace(/^www\./, "").replace(/\./g, "\\.")}/`
-	}] }];
+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?://(www\\.)?${domainFilter.domain.replace(/^www\./, "").replace(/\./g, "\\.")}/`;
+		out.push({
+			dimension: "page",
+			operator: "includingRegex",
+			expression: pattern
+		});
+	}
+	return out.length > 0 ? [{ filters: out }] : void 0;
 }
 async function runGscSyncSlice(opts) {
 	const rowLimit = opts.rowLimit ?? 500;
@@ -193,7 +209,7 @@ async function runGscSyncSlice(opts) {
 	const searchType = opts.searchType ?? "web";
 	const dimensions = opts.dimensions ? [...opts.dimensions] : [...DIMENSIONS_BY_TABLE[opts.table]];
 	const dataState = opts.dataState ?? "all";
-	const dimensionFilterGroups = buildDomainFilterGroups(opts.domainFilter);
+	const dimensionFilterGroups = buildDimensionFilterGroups(opts.domainFilter, opts.dimensionFilters);
 	const loopStart = Date.now();
 	let startRow = opts.initialStartRow ?? 0;
 	let totalRows = 0;
@@ -261,4 +277,76 @@ async function runGscSyncSlice(opts) {
 		metadata
 	};
 }
-export { canProxyToGsc, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN, runGscSyncSlice };
+function contextTableForGrain(grain) {
+	switch (grain) {
+		case "page": return "search_appearance_pages";
+		case "query": return "search_appearance_queries";
+		case "page_query": return "search_appearance_page_queries";
+	}
+}
+async function runGscSearchAppearanceContextSlice(opts) {
+	const table = opts.table ?? contextTableForGrain(opts.grain ?? "page_query");
+	const appearances = opts.appearances?.slice() ?? [];
+	let totalRows = 0;
+	let hasMore = false;
+	if (!opts.appearances) {
+		const discovered = /* @__PURE__ */ new Set();
+		const discovery = await runGscSyncSlice({
+			client: opts.client,
+			siteUrl: opts.siteUrl,
+			table: "search_appearance",
+			startDate: opts.startDate,
+			endDate: opts.endDate,
+			domainFilter: opts.domainFilter,
+			dataState: opts.dataState,
+			rowLimit: opts.rowLimit,
+			maxPages: opts.maxPages,
+			cpuBudgetMs: opts.cpuBudgetMs,
+			searchType: opts.searchType,
+			onPage: opts.onPage,
+			onBatch: async (rows) => {
+				for (const row of rows) {
+					const value = String(row.keys?.[0] ?? "");
+					if (value) discovered.add(value);
+				}
+				await opts.onTotalBatch?.(rows);
+			}
+		});
+		totalRows += discovery.totalRows;
+		hasMore ||= discovery.hasMore;
+		appearances.push(...discovered);
+	}
+	for (const searchAppearance of appearances) {
+		const context = await runGscSyncSlice({
+			client: opts.client,
+			siteUrl: opts.siteUrl,
+			table,
+			startDate: opts.startDate,
+			endDate: opts.endDate,
+			domainFilter: opts.domainFilter,
+			dimensionFilters: [{
+				dimension: "searchAppearance",
+				expression: searchAppearance
+			}],
+			dataState: opts.dataState,
+			rowLimit: opts.rowLimit,
+			maxPages: opts.maxPages,
+			cpuBudgetMs: opts.cpuBudgetMs,
+			searchType: opts.searchType,
+			onPage: opts.onPage,
+			onBatch: (rows) => opts.onContextBatch({
+				searchAppearance,
+				table,
+				rows
+			})
+		});
+		totalRows += context.totalRows;
+		hasMore ||= context.hasMore;
+	}
+	return {
+		appearances,
+		totalRows,
+		hasMore
+	};
+}
+export { canProxyToGsc, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN, runGscSearchAppearanceContextSlice, runGscSyncSlice };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine-gsc-api",
   "type": "module",
-  "version": "0.21.3",
+  "version": "0.22.1",
   "description": "GSC live-API engine adapter — wraps the Search Analytics REST API as an AnalysisQuerySource for typed analyzer dispatch.",
   "author": {
     "name": "Harlan Wilton",
@@ -36,11 +36,11 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@gscdump/engine": "0.21.3",
-    "gscdump": "0.21.3"
+    "gscdump": "0.22.1",
+    "@gscdump/engine": "0.22.1"
   },
   "devDependencies": {
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.7"
   },
   "scripts": {
     "build": "obuild",