@gscdump/engine-gsc-api 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Harlan Wilton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @gscdump/engine-gsc-api
+
+[![npm version](https://img.shields.io/npm/v/@gscdump/engine-gsc-api?color=yellow)](https://npmjs.com/package/@gscdump/engine-gsc-api)
+[![npm downloads](https://img.shields.io/npm/dm/@gscdump/engine-gsc-api?color=yellow)](https://npm.chart.dev/@gscdump/engine-gsc-api)
+[![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)
+
+> GSC live-API engine adapter — wraps the Search Analytics REST API as an `AnalysisQuerySource` for typed analyzer dispatch.
+
+Wraps the Google Search Console live REST API as a `RowQuerySource` so row-based analyzers (`striking-distance`, `opportunity`, `movers`, `decay`, `brand`, `clustering`, `concentration`, `seasonality`) dispatch through the same `runAnalyzerFromSource` pipeline as engine-backed sources.
+
+Use this when you have a GSC OAuth token but no synced parquet data — free-tier flows, demo pages, queries whose date range falls outside the synced window. Pair with `createCompositeSource` to fall back to GSC for out-of-range queries.
+
+## Install
+
+```bash
+npm install @gscdump/engine-gsc-api @gscdump/engine gscdump
+```
+
+## Usage
+
+```ts
+import { analyzeMoversFromSource } from '@gscdump/analysis'
+import { createGscApiQuerySource } from '@gscdump/engine-gsc-api'
+import { googleSearchConsole } from 'gscdump'
+
+const client = googleSearchConsole(auth)
+const source = createGscApiQuerySource({ client, siteUrl: 'sc-domain:example.com' })
+
+const movers = await analyzeMoversFromSource(source, {
+  current: { startDate: '2026-04-01', endDate: '2026-04-28' },
+  previous: { startDate: '2026-03-01', endDate: '2026-03-31' },
+})
+```
+
+For host apps that mint short-lived access tokens per request:
+
+```ts
+import { createLiveGscSource } from '@gscdump/engine-gsc-api'
+
+const source = createLiveGscSource({
+  siteUrl,
+  getAccessToken: () => refreshAccessTokenForUser(userId),
+})
+```
+
+## Exports
+
+- `createGscApiQuerySource({ client, siteUrl })` — `RowQuerySource` over a `GoogleSearchConsoleClient`.
+- `createLiveGscSource({ siteUrl, getAccessToken })` — token-refresh wrapper on top of `createGscApiQuerySource`.
+- `canProxyToGsc(state)` — guard for `createCompositeSource`: returns `true` if a `BuilderState` can be answered by GSC's native API (no metric filters, no engine-derived dimensions).
+- `fetchGscTopN({ client, siteUrl, dimension, range, limit })` — typed top-N rollup helper.
+- `fetchGscDaily({ client, siteUrl, range })` — typed daily timeseries helper.
+- `collectGscRows(asyncIterable)` — drain `client.query()` into an array.
+- `applyBuilderStatePostProcessing(rows, state)` — post-process row collections for predicates GSC can't push down (metric filters, special operators).
+- `GSC_API_CAPABILITIES` — `PlannerCapabilities` for the GSC API surface.
+
+## Capabilities
+
+GSC supports regex pushdown via `INCLUDING_REGEX` / `EXCLUDING_REGEX` filters but has no SQL surface, no comparison joins, no cross-dataset queries, and no engine-derived dimensions (`queryCanonical`, `page_keywords`). Pair with `createCompositeSource({ engine, gsc })` from `@gscdump/analysis/source` to route SQL-shaped queries to the engine and date-out-of-range queries to GSC.
+
+## Related
+
+- [`@gscdump/engine`](../engine) — Source contracts (`RowQuerySource`, `AnalysisQuerySource`).
+- [`@gscdump/analysis`](../analysis) — Analyzer instances + `createCompositeSource`.
+- [`gscdump`](../gscdump) — REST client + query builder.
+
+## License
+
+[MIT](../../LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,69 @@
+import { GoogleSearchConsoleClient } from "gscdump";
+import { BuilderState, Column, Dimension } from "gscdump/query";
+import { AnalysisQuerySource, RowQuerySource } from "@gscdump/engine/resolver";
+import { PlannerCapabilities } from "gscdump/query/plan";
+declare function canProxyToGsc(state: BuilderState): boolean;
+interface CreateLiveGscSourceOptions {
+  /** GSC property URL (e.g. `sc-domain:example.com` or `https://example.com/`). */
+  siteUrl: string;
+  /**
+   * Returns a valid GSC access token. Called lazily on first query so refresh
+   * cost is paid only when the source actually runs. Host owns refresh logic.
+   */
+  getAccessToken: () => Promise<string>;
+}
+declare function createLiveGscSource(opts: CreateLiveGscSourceOptions): AnalysisQuerySource;
+declare function applyBuilderStatePostProcessing(rows: Record<string, unknown>[], state: BuilderState): Record<string, unknown>[];
+declare function collectRows<T>(gen: AsyncGenerator<T[]>): Promise<T[]>;
+interface GscRange {
+  start: string;
+  end: string;
+}
+interface GscTopNRow {
+  key: string;
+  clicks: number;
+  impressions: number;
+  sum_position: number;
+}
+interface FetchTopNOptions<D extends Dimension> {
+  client: GoogleSearchConsoleClient;
+  siteUrl: string;
+  dimension: Column<D>;
+  range: GscRange;
+  /**
+   * Ask the GSC API to order by clicks desc. Skip for dimensions where GSC
+   * already returns sensibly ranked rows (e.g. country).
+   */
+  orderByClicksDesc?: boolean;
+  /** Forwarded to the GSC builder. */
+  limit?: number;
+  /** Trim after the fact (e.g. country has no server-side limit). */
+  sliceTop?: number;
+}
+declare function fetchGscTopN<D extends Dimension>(opts: FetchTopNOptions<D>): Promise<GscTopNRow[]>;
+interface GscDailyRow {
+  date: number;
+  clicks: number;
+  impressions: number;
+  sum_position: number;
+  anonymizedImpressionsPct: number;
+}
+declare function fetchGscDaily(opts: {
+  client: GoogleSearchConsoleClient;
+  siteUrl: string;
+  range: GscRange;
+}): Promise<GscDailyRow[]>;
+/**
+ * Capabilities the live GSC API can satisfy. Regex pushes down via the
+ * `INCLUDING_REGEX` / `EXCLUDING_REGEX` filter types; comparison joins and
+ * cross-dataset queries do not exist on the wire, and the API does not
+ * expose window aggregations. Metric filters and ordering are honored by
+ * the source-layer post-process pass after row collection.
+ */
+declare const GSC_API_CAPABILITIES: PlannerCapabilities;
+interface GscApiQuerySourceOptions {
+  client: GoogleSearchConsoleClient;
+  siteUrl: string;
+}
+declare function createGscApiQuerySource(options: GscApiQuerySourceOptions): RowQuerySource;
+export { type CreateLiveGscSourceOptions, type FetchTopNOptions, GSC_API_CAPABILITIES, type GscApiQuerySourceOptions, type GscDailyRow, type GscRange, type GscTopNRow, applyBuilderStatePostProcessing, canProxyToGsc, collectRows as collectGscRows, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN };

package/dist/index.mjs

@@ -0,0 +1,137 @@
+import { googleSearchConsole } from "gscdump";
+import { between, clicks, date, extractMetricFilters, extractSpecialOperatorFilters, gsc } from "gscdump/query";
+import { assertDimensionsSupported, getDimensionFilters, getFilterDimensions, matchesDimensionFilter, matchesMetricFilter, matchesTopLevelPage, metricValue } from "@gscdump/engine/resolver";
+import { buildLogicalPlan } from "gscdump/query/plan";
+const METRIC_NAMES = [
+	"clicks",
+	"impressions",
+	"ctr",
+	"position"
+];
+function isMetricDimension$1(dim) {
+	return METRIC_NAMES.includes(dim);
+}
+function applyBuilderStatePostProcessing(rows, state) {
+	const dimensionFilters = getDimensionFilters(state.filter, isMetricDimension$1);
+	const metricFilters = extractMetricFilters(state.filter);
+	const specialFilters = extractSpecialOperatorFilters(state.filter);
+	const ordered = [...rows.filter((row) => {
+		if (!dimensionFilters.every((filter) => matchesDimensionFilter(row, filter))) return false;
+		if (!metricFilters.every((filter) => matchesMetricFilter(row, filter))) return false;
+		if (specialFilters.some((filter) => filter.operator === "topLevel") && !matchesTopLevelPage(row)) return false;
+		return true;
+	})].sort((a, b) => {
+		const column = state.orderBy?.column ?? "clicks";
+		const dir = state.orderBy?.dir ?? "desc";
+		const left = column === "date" ? String(a.date ?? "") : metricValue(a, column);
+		const right = column === "date" ? String(b.date ?? "") : metricValue(b, column);
+		if (left === right) return 0;
+		if (dir === "asc") return left < right ? -1 : 1;
+		return left > right ? -1 : 1;
+	});
+	const offset = Math.max(0, Number(state.startRow ?? 0));
+	const limit = Math.max(0, Number((state.rowLimit ?? ordered.length) || 0));
+	return ordered.slice(offset, offset + limit);
+}
+async function collectRows(gen) {
+	const out = [];
+	for await (const batch of gen) out.push(...batch);
+	return out;
+}
+async function fetchGscTopN(opts) {
+	const { client, siteUrl, dimension, range, orderByClicksDesc, limit, sliceTop } = opts;
+	let builder = gsc.select(dimension).where(between(date, range.start, range.end));
+	if (orderByClicksDesc) builder = builder.orderBy(clicks, "desc");
+	if (typeof limit === "number") builder = builder.limit(limit);
+	const mapped = (await collectRows(client.query(siteUrl, builder))).map((r) => {
+		const row = r;
+		const key = row[dimension.dimension];
+		if (typeof key !== "string" || !key) return null;
+		const impressions = Number(row.impressions ?? 0);
+		const position = Number(row.position ?? 0);
+		return {
+			key,
+			clicks: Number(row.clicks ?? 0),
+			impressions,
+			sum_position: position * impressions
+		};
+	}).filter((x) => x != null);
+	if (!orderByClicksDesc) mapped.sort((a, b) => b.clicks - a.clicks);
+	return typeof sliceTop === "number" ? mapped.slice(0, sliceTop) : mapped;
+}
+async function fetchGscDaily(opts) {
+	const { client, siteUrl, range } = opts;
+	const builder = gsc.select(date).where(between(date, range.start, range.end));
+	return (await collectRows(client.query(siteUrl, builder))).map((r) => {
+		const row = r;
+		if (!row.date) return null;
+		const impressions = row.impressions ?? 0;
+		return {
+			date: Date.parse(`${row.date}T00:00:00Z`),
+			clicks: row.clicks ?? 0,
+			impressions,
+			sum_position: (row.position ?? 0) * impressions,
+			anonymizedImpressionsPct: 0
+		};
+	}).filter((x) => x != null).sort((a, b) => a.date - b.date);
+}
+const GSC_API_CAPABILITIES = {
+	regex: true,
+	multiDataset: false,
+	comparisonJoin: false,
+	windowTotals: false
+};
+function isMetricDimension(dim) {
+	return [
+		"clicks",
+		"impressions",
+		"ctr",
+		"position"
+	].includes(dim);
+}
+function builderFromState(state) {
+	return { getState: () => state };
+}
+function createGscApiQuerySource(options) {
+	const { client, siteUrl } = options;
+	return {
+		name: "gsc-api",
+		capabilities: GSC_API_CAPABILITIES,
+		async queryRows(state) {
+			buildLogicalPlan(state, GSC_API_CAPABILITIES);
+			const filterDims = getFilterDimensions(state.filter, isMetricDimension);
+			assertDimensionsSupported([...state.dimensions, ...filterDims], "api", "gsc-api query source");
+			return applyBuilderStatePostProcessing(await collectRows(client.query(siteUrl, builderFromState(state))), state);
+		}
+	};
+}
+const PRO_ONLY_DIMENSIONS = new Set(["queryCanonical", "page_keywords"]);
+function canProxyToGsc(state) {
+	if (state.dimensions.some((d) => PRO_ONLY_DIMENSIONS.has(d))) return false;
+	if (extractMetricFilters(state.filter).length > 0) return false;
+	if (extractSpecialOperatorFilters(state.filter).length > 0) return false;
+	return true;
+}
+function createLiveGscSource(opts) {
+	let clientPromise = null;
+	function getClient() {
+		if (!clientPromise) clientPromise = opts.getAccessToken().then((accessToken) => googleSearchConsole({ accessToken }));
+		return clientPromise;
+	}
+	return {
+		name: "gsc-api",
+		capabilities: {
+			regex: true,
+			multiDataset: false,
+			comparisonJoin: false,
+			windowTotals: false
+		},
+		async queryRows(state) {
+			return createGscApiQuerySource({
+				client: await getClient(),
+				siteUrl: opts.siteUrl
+			}).queryRows(state);
+		}
+	};
+}
+export { GSC_API_CAPABILITIES, applyBuilderStatePostProcessing, canProxyToGsc, collectRows as collectGscRows, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@gscdump/engine-gsc-api",
+  "type": "module",
+  "version": "0.7.1",
+  "description": "GSC live-API engine adapter — wraps the Search Analytics REST API as an AnalysisQuerySource for typed analyzer dispatch.",
+  "author": {
+    "name": "Harlan Wilton",
+    "email": "harlan@harlanzw.com",
+    "url": "https://harlanzw.com/"
+  },
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/harlan-zw",
+  "homepage": "https://github.com/harlan-zw/gscdump/tree/main/packages/engine-gsc-api#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harlan-zw/gscdump.git",
+    "directory": "packages/engine-gsc-api"
+  },
+  "bugs": {
+    "url": "https://github.com/harlan-zw/gscdump/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@gscdump/engine": "0.7.1",
+    "gscdump": "0.7.1"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "obuild",
+    "dev": "obuild --stub",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --passWithNoTests"
+  }
+}