@gscdump/engine-gsc-api 0.17.5 → 0.18.1

package/dist/index.d.mts

@@ -2,6 +2,7 @@ import { GoogleSearchConsoleClient } from "gscdump";
 import { BuilderState, Column, Dimension } from "gscdump/query";
 import { SearchType } from "@gscdump/engine";
 import { AnalysisQuerySource } from "@gscdump/engine/source";
+import { GscDataState, GscSearchAnalyticsMetadata } from "gscdump/contracts";
 declare function canProxyToGsc(state: BuilderState): boolean;
 interface CreateLiveGscSourceOptions {
   /** GSC property URL (e.g. `sc-domain:example.com` or `https://example.com/`). */
@@ -82,10 +83,21 @@ interface RunGscSyncSliceOptions {
   client: GoogleSearchConsoleClient;
   siteUrl: string;
   /** One of the engine sync-fan tables. Drives the dimension list. */
-  table: 'pages' | 'keywords' | 'countries' | 'devices' | 'page_keywords';
+  table: 'pages' | 'keywords' | 'countries' | 'devices' | 'page_keywords' | 'hourly_pages';
   startDate: string;
   endDate: string;
   domainFilter?: SyncSliceDomainFilter | null;
+  /**
+   * Override the dimension list for this slice. Defaults to
+   *  `DIMENSIONS_BY_TABLE[table]`. Hosts that need bespoke groupings (e.g.
+   *  hourly Discover variants) supply this directly.
+   */
+  dimensions?: string[];
+  /**
+   * GSC `dataState` for the query. Defaults to `'all'`. Use `'hourly_all'`
+   *  for hourly Discover slices.
+   */
+  dataState?: GscDataState;
   /**
    * Invoked per GSC API page with the rows fetched. Return a promise; the
    *  loop awaits it before paging further. Throw inside to abort; AbortError /
@@ -116,6 +128,12 @@ interface RunGscSyncSliceResult {
   totalRows: number;
   hasMore: boolean;
   nextStartRow: number;
+  /**
+   * Metadata from the LAST GSC API page seen during this slice run. When
+   *  `dataState='hourly_all'` and grouped by `hour`, this surfaces
+   *  `first_incomplete_hour` so hosts can watermark hourly progress.
+   */
+  metadata?: GscSearchAnalyticsMetadata;
 }
 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 };

package/dist/index.mjs

@@ -168,7 +168,8 @@ const DIMENSIONS_BY_TABLE = {
 		"page",
 		"query",
 		"date"
-	]
+	],
+	hourly_pages: ["hour", "page"]
 };
 function isTimeoutLike(err) {
 	if (!(err instanceof Error)) return false;
@@ -187,22 +188,26 @@ async function runGscSyncSlice(opts) {
 	const cpuBudgetMs = opts.cpuBudgetMs ?? 2e4;
 	const maxPages = opts.maxPages ?? Infinity;
 	const searchType = opts.searchType ?? "web";
-	const dimensions = [...DIMENSIONS_BY_TABLE[opts.table]];
+	const dimensions = opts.dimensions ? [...opts.dimensions] : [...DIMENSIONS_BY_TABLE[opts.table]];
+	const dataState = opts.dataState ?? "all";
 	const dimensionFilterGroups = buildDomainFilterGroups(opts.domainFilter);
 	const loopStart = Date.now();
 	let startRow = opts.initialStartRow ?? 0;
 	let totalRows = 0;
 	let pageCount = 0;
+	let metadata;
 	while (true) {
 		if (pageCount >= maxPages) return {
 			totalRows,
 			hasMore: true,
-			nextStartRow: startRow
+			nextStartRow: startRow,
+			metadata
 		};
 		if (Date.now() - loopStart >= cpuBudgetMs) return {
 			totalRows,
 			hasMore: true,
-			nextStartRow: startRow
+			nextStartRow: startRow,
+			metadata
 		};
 		const query = {
 			startDate: opts.startDate,
@@ -210,8 +215,8 @@ async function runGscSyncSlice(opts) {
 			dimensions,
 			rowLimit,
 			startRow,
-			dataState: "all",
-			searchType,
+			dataState,
+			type: searchType,
 			...dimensionFilterGroups ? { dimensionFilterGroups } : {}
 		};
 		const response = await opts.client._rawQuery(opts.siteUrl, query).catch((err) => {
@@ -221,11 +226,13 @@ async function runGscSyncSlice(opts) {
 		if (!response) return {
 			totalRows,
 			hasMore: true,
-			nextStartRow: startRow
+			nextStartRow: startRow,
+			metadata
 		};
 		const rows = response.rows ?? [];
 		totalRows += rows.length;
 		pageCount++;
+		if (response.metadata) metadata = response.metadata;
 		opts.onPage?.({
 			searchType,
 			rowsThisPage: rows.length
@@ -240,7 +247,8 @@ async function runGscSyncSlice(opts) {
 	return {
 		totalRows,
 		hasMore: false,
-		nextStartRow: startRow
+		nextStartRow: startRow,
+		metadata
 	};
 }
 export { canProxyToGsc, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN, runGscSyncSlice };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine-gsc-api",
   "type": "module",
-  "version": "0.17.5",
+  "version": "0.18.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,8 +36,8 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@gscdump/engine": "0.17.5",
-    "gscdump": "0.17.5"
+    "@gscdump/engine": "0.18.1",
+    "gscdump": "0.18.1"
   },
   "devDependencies": {
     "vitest": "^4.1.6"