@gscdump/engine-gsc-api 3.4.4 → 3.6.0

package/README.md

@@ -4,65 +4,66 @@
 [![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.
+Use Google Search Console as an `AnalysisQuerySource`.
+This adapter runs Analyzers with row plans without a local Store.
 
 ## Install
 
 ```bash
-npm install @gscdump/engine-gsc-api @gscdump/engine gscdump
+npm install @gscdump/engine-gsc-api @gscdump/analysis gscdump
 ```
 
-## Usage
+## Query live rows
 
 ```ts
-import { analyzeMoversFromSource } from '@gscdump/analysis'
 import { createGscApiQuerySource } from '@gscdump/engine-gsc-api'
 import { googleSearchConsole } from 'gscdump'
+import { between, date, gsc, page } from 'gscdump/query'
 
-const client = googleSearchConsole(auth)
+const client = googleSearchConsole({ accessToken: process.env.GSC_ACCESS_TOKEN! })
 const source = createGscApiQuerySource({ client, siteUrl: 'sc-domain:example.com' })
+const state = gsc.select(page)
+  .where(between(date, '2026-08-01', '2026-08-28'))
+  .limit(100)
+  .getState()
 
-const movers = await analyzeMoversFromSource(source, {
-  current: { startDate: '2026-04-01', endDate: '2026-04-28' },
-  previous: { startDate: '2026-03-01', endDate: '2026-03-31' },
-})
+const rows = await source.queryRows(state)
+console.log(rows)
 ```
 
-For host apps that mint short-lived access tokens per request:
+See [`@gscdump/analysis`](../analysis/README.md#sources) for Analyzer dispatch.
 
-```ts
-import { createLiveGscSource } from '@gscdump/engine-gsc-api'
+## Deferred authentication
 
-const source = createLiveGscSource({
-  siteUrl,
-  getAccessToken: () => refreshAccessTokenForUser(userId),
-})
-```
+`createLiveGscSource({ siteUrl, getAccessToken })` calls your token function on the first query.
+It reuses the resulting client for that Source's lifetime.
+Create a Source per request if your host manages token refresh between requests.
 
 ## 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 and portable source factories.
-- [`gscdump`](../gscdump) — REST client + query builder.
+| Export | Purpose |
+| --- | --- |
+| `createGscApiQuerySource` | Wrap a Google client as a Source |
+| `createLiveGscSource` | Create a Source with deferred token lookup |
+| `canProxyToGsc` | Check whether query inputs support live routing |
+| `fetchGscTopN` | Read top rows for a dimension and date range |
+| `fetchGscDaily` | Read daily metrics |
+| `runGscSyncSlice` | Read a bounded Search Analytics sync slice |
+| `runGscSearchAppearanceContextSlice` | Read a Search Appearance context slice |
+
+## Limits and fallback
+
+The Source supports row queries and regex filters.
+It has no SQL execution, comparison joins, or Engine-derived dimensions such as `queryCanonical`.
+`canProxyToGsc` rejects malformed inputs, prefilters, and Engine-derived dimensions in selections or filters.
+Metric filters remain supported after row collection.
+
+`createCompositeSource` from `@gscdump/analysis/source` accepts `{ engine, live, site }`.
+It sends supported queries to Google when stored coverage or dimensions cannot answer them.
+The `site` input supplies sync bounds and optional covered date spans.
+SQL execution uses the Engine.
+
+Google's [Search Analytics limits](https://developers.google.com/webmaster-tools/v1/how-tos/all-your-data) still apply.
 
 ## License
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { CreateLiveGscSourceOptions, canProxyToGsc, createLiveGscSource } from "./live.mjs";
 import { FetchTopNOptions, GscDailyRow, GscRange, GscTopNRow, fetchGscDaily, fetchGscTopN } from "./rollup-synth.mjs";
-import { GscApiQuerySourceOptions, createGscApiQuerySource } from "./source.mjs";
+import { GSC_API_CAPABILITIES, GscApiQuerySourceOptions, createGscApiQuerySource } from "./source.mjs";
 import { GscApiRow, RunGscSearchAppearanceContextSliceOptions, RunGscSearchAppearanceContextSliceResult, RunGscSyncSliceOptions, RunGscSyncSliceResult, SearchAppearanceContextGrain, SearchAppearanceContextTable, SyncSliceDimensionFilter, SyncSliceDomainFilter, runGscSearchAppearanceContextSlice, runGscSyncSlice } from "./sync-slice.mjs";
-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 };
+export { type CreateLiveGscSourceOptions, type FetchTopNOptions, GSC_API_CAPABILITIES, 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

@@ -1,5 +1,5 @@
 import { fetchGscDaily, fetchGscTopN } from "./rollup-synth.mjs";
-import { createGscApiQuerySource } from "./source.mjs";
+import { GSC_API_CAPABILITIES, createGscApiQuerySource } from "./source.mjs";
 import { canProxyToGsc, createLiveGscSource } from "./live.mjs";
 import { runGscSearchAppearanceContextSlice, runGscSyncSlice } from "./sync-slice.mjs";
-export { canProxyToGsc, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN, runGscSearchAppearanceContextSlice, runGscSyncSlice };
+export { GSC_API_CAPABILITIES, canProxyToGsc, createGscApiQuerySource, createLiveGscSource, fetchGscDaily, fetchGscTopN, runGscSearchAppearanceContextSlice, runGscSyncSlice };

package/dist/live.d.mts

@@ -2,8 +2,8 @@ import { GoogleSearchConsoleClient } from "gscdump";
 import { BuilderState } from "gscdump/query";
 import { SearchType as SearchType$1 } from "@gscdump/engine";
 import { AnalysisQuerySource } from "@gscdump/engine/source";
-declare function canProxyToGsc(state: BuilderState): boolean;
-interface CreateLiveGscSourceOptions {
+export declare function canProxyToGsc(state: BuilderState): boolean;
+export interface CreateLiveGscSourceOptions {
   /** GSC property URL (e.g. `sc-domain:example.com` or `https://example.com/`). */
   siteUrl: string;
   /**
@@ -21,5 +21,4 @@ interface CreateLiveGscSourceOptions {
    */
   searchType?: SearchType$1;
 }
-declare function createLiveGscSource(opts: CreateLiveGscSourceOptions): AnalysisQuerySource;
-export { CreateLiveGscSourceOptions, canProxyToGsc, createLiveGscSource };
+export declare function createLiveGscSource(opts: CreateLiveGscSourceOptions): AnalysisQuerySource;

package/dist/live.mjs

@@ -1,9 +1,15 @@
 import { createGscApiQuerySource } from "./source.mjs";
 import { googleSearchConsole } from "gscdump";
+import { normalizeBuilderStateResult } 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)));
+}
 function canProxyToGsc(state) {
-	if (state.dimensions.some((d) => PRO_ONLY_DIMENSIONS.has(d))) return false;
-	return true;
+	const parsed = normalizeBuilderStateResult(state);
+	if (!parsed.ok) return false;
+	const normalized = parsed.value;
+	return !hasMatchingFilter(normalized.prefilter, () => true) && !normalized.dimensions.some((d) => PRO_ONLY_DIMENSIONS.has(d)) && !hasMatchingFilter(normalized.filter, (dimension) => PRO_ONLY_DIMENSIONS.has(dimension));
 }
 function withSearchType(state, searchType) {
 	return state.searchType ? state : {
@@ -14,7 +20,10 @@ function withSearchType(state, searchType) {
 function createLiveGscSource(opts) {
 	let clientPromise = null;
 	function getClient() {
-		if (!clientPromise) clientPromise = opts.getAccessToken().then((accessToken) => opts.createClient?.(accessToken) ?? googleSearchConsole({ accessToken }));
+		if (!clientPromise) clientPromise = opts.getAccessToken().then((accessToken) => opts.createClient?.(accessToken) ?? googleSearchConsole({ accessToken })).catch((error) => {
+			clientPromise = null;
+			throw error;
+		});
 		return clientPromise;
 	}
 	return {

package/dist/post-process.mjs

@@ -1,5 +1,5 @@
-import { dimensionValue, matchesTopLevelPage, metricValue } from "@gscdump/engine/resolver";
 import { extractMetricFilters, extractSpecialOperatorFilters } from "gscdump/query";
+import { dimensionValue, matchesTopLevelPage, metricValue } from "@gscdump/engine/resolver";
 import { normalizeUrl } from "gscdump/normalize";
 const METRIC_NAMES = [
 	"clicks",

package/dist/rollup-synth.d.mts

@@ -1,16 +1,16 @@
 import { GoogleSearchConsoleClient } from "gscdump";
 import { Column, Dimension, SearchType } from "gscdump/query";
-interface GscRange {
+export interface GscRange {
   start: string;
   end: string;
 }
-interface GscTopNRow {
+export interface GscTopNRow {
   key: string;
   clicks: number;
   impressions: number;
   sum_position: number;
 }
-interface FetchTopNOptions<D extends Dimension> {
+export interface FetchTopNOptions<D extends Dimension> {
   client: GoogleSearchConsoleClient;
   siteUrl: string;
   dimension: Column<D>;
@@ -27,19 +27,18 @@ interface FetchTopNOptions<D extends Dimension> {
   /** GSC search corpus; callers default API-boundary omissions to web. */
   searchType?: SearchType;
 }
-declare function fetchGscTopN<D extends Dimension>(opts: FetchTopNOptions<D>): Promise<GscTopNRow[]>;
-interface GscDailyRow {
+export declare function fetchGscTopN<D extends Dimension>(opts: FetchTopNOptions<D>): Promise<GscTopNRow[]>;
+export interface GscDailyRow {
   date: number;
   clicks: number;
   impressions: number;
   sum_position: number;
   anonymizedImpressionsPct: number;
 }
-declare function fetchGscDaily(opts: {
+export declare function fetchGscDaily(opts: {
   client: GoogleSearchConsoleClient;
   siteUrl: string;
   range: GscRange;
   /** GSC search corpus; callers default API-boundary omissions to web. */
   searchType?: SearchType;
-}): Promise<GscDailyRow[]>;
-export { FetchTopNOptions, GscDailyRow, GscRange, GscTopNRow, fetchGscDaily, fetchGscTopN };
+}): Promise<GscDailyRow[]>;

package/dist/source.d.mts

@@ -1,8 +1,16 @@
 import { GoogleSearchConsoleClient } from "gscdump";
+import { PlannerCapabilities } from "gscdump/query/plan";
 import { AnalysisQuerySource } from "@gscdump/engine/source";
-interface GscApiQuerySourceOptions {
+/**
+ * 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.
+ */
+export declare const GSC_API_CAPABILITIES: PlannerCapabilities;
+export interface GscApiQuerySourceOptions {
   client: GoogleSearchConsoleClient;
   siteUrl: string;
 }
-declare function createGscApiQuerySource(options: GscApiQuerySourceOptions): AnalysisQuerySource;
-export { GscApiQuerySourceOptions, createGscApiQuerySource };
+export declare function createGscApiQuerySource(options: GscApiQuerySourceOptions): AnalysisQuerySource;

package/dist/source.mjs

@@ -1,7 +1,7 @@
 import { applyBuilderStatePostProcessing } from "./post-process.mjs";
 import { collectRows } from "./rollup-synth.mjs";
-import { assertDimensionsSupported, getFilterDimensions } from "@gscdump/engine/resolver";
-import { extractMetricFilters, extractSpecialOperatorFilters } from "gscdump/query";
+import { UnsupportedLogicalCapabilityError, extractMetricFilters, extractSpecialOperatorFilters, normalizeFilter } from "gscdump/query";
+import { assertDimensionsSupported, getFilterDimensions, getInternalFilters } from "@gscdump/engine/resolver";
 import { buildLogicalPlan } from "gscdump/query/plan";
 const GSC_API_CAPABILITIES = {
 	regex: true,
@@ -30,6 +30,7 @@ function createGscApiQuerySource(options) {
 		kind: "live",
 		capabilities: GSC_API_CAPABILITIES,
 		async queryRows(state) {
+			if (getInternalFilters(normalizeFilter(state.prefilter)).length > 0) throw new UnsupportedLogicalCapabilityError("prefilter", "gsc-api query source");
 			buildLogicalPlan(state, GSC_API_CAPABILITIES);
 			const filterDims = getFilterDimensions(state.filter, isMetricDimension);
 			assertDimensionsSupported([...state.dimensions, ...filterDims], "api", "gsc-api query source");

package/dist/sync-slice.d.mts

@@ -1,26 +1,26 @@
 import { GoogleSearchConsoleClient } from "gscdump";
 import { SearchType } from "@gscdump/engine";
 import { GscDataState, GscSearchAnalyticsMetadata } from "gscdump/contracts";
-interface GscApiRow {
+export interface GscApiRow {
   keys: string[];
   clicks: number;
   impressions: number;
   ctr: number;
   position: number;
 }
-interface SyncSliceDomainFilter {
+export interface SyncSliceDomainFilter {
   /**
    * Domain (eTLD+1 + subdomain) to scope the slice to — matches both
    *  `www.` and bare variants. Strip the protocol; the regex is built here.
    */
   domain?: string;
 }
-interface SyncSliceDimensionFilter {
+export interface SyncSliceDimensionFilter {
   dimension: 'page' | 'query' | 'country' | 'device' | 'searchAppearance';
   operator?: 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
   expression: string;
 }
-interface RunGscSyncSliceOptions {
+export interface RunGscSyncSliceOptions {
   client: GoogleSearchConsoleClient;
   siteUrl: string;
   /** One of the engine sync-fan tables. Drives the dimension list. */
@@ -68,7 +68,7 @@ interface RunGscSyncSliceOptions {
     rowsThisPage: number;
   }) => void;
 }
-interface RunGscSyncSliceResult {
+export interface RunGscSyncSliceResult {
   totalRows: number;
   hasMore: boolean;
   nextStartRow: number;
@@ -79,9 +79,9 @@ interface RunGscSyncSliceResult {
    */
   metadata?: GscSearchAnalyticsMetadata;
 }
-type SearchAppearanceContextGrain = 'page' | 'query' | 'page_query';
-type SearchAppearanceContextTable = 'search_appearance_pages' | 'search_appearance_queries' | 'search_appearance_page_queries';
-interface RunGscSearchAppearanceContextSliceOptions {
+export type SearchAppearanceContextGrain = 'page' | 'query' | 'page_query';
+export type SearchAppearanceContextTable = 'search_appearance_pages' | 'search_appearance_queries' | 'search_appearance_page_queries';
+export interface RunGscSearchAppearanceContextSliceOptions {
   client: GoogleSearchConsoleClient;
   siteUrl: string;
   startDate: string;
@@ -110,7 +110,7 @@ interface RunGscSearchAppearanceContextSliceOptions {
   }) => void;
   continuation?: SearchAppearanceContinuation;
 }
-type SearchAppearanceContinuation = {
+export type SearchAppearanceContinuation = {
   phase: 'discovery';
   appearances: string[];
   nextStartRow: number;
@@ -120,17 +120,16 @@ type SearchAppearanceContinuation = {
   appearanceIndex: number;
   nextStartRow: number;
 };
-interface RunGscSearchAppearanceContextSliceResult {
+export interface RunGscSearchAppearanceContextSliceResult {
   appearances: string[];
   totalRows: number;
   hasMore: boolean;
   continuation?: SearchAppearanceContinuation;
 }
-declare function runGscSyncSlice(opts: RunGscSyncSliceOptions): Promise<RunGscSyncSliceResult>;
+export declare function runGscSyncSlice(opts: RunGscSyncSliceOptions): Promise<RunGscSyncSliceResult>;
 /**
  * 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 { GscApiRow, RunGscSearchAppearanceContextSliceOptions, RunGscSearchAppearanceContextSliceResult, RunGscSyncSliceOptions, RunGscSyncSliceResult, SearchAppearanceContextGrain, SearchAppearanceContextTable, SearchAppearanceContinuation, SyncSliceDimensionFilter, SyncSliceDomainFilter, runGscSearchAppearanceContextSlice, runGscSyncSlice };
+export declare function runGscSearchAppearanceContextSlice(opts: RunGscSearchAppearanceContextSliceOptions): Promise<RunGscSearchAppearanceContextSliceResult>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine-gsc-api",
   "type": "module",
-  "version": "3.4.4",
+  "version": "3.6.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,11 +36,11 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@gscdump/engine": "^3.4.4",
-    "gscdump": "^3.4.4"
+    "@gscdump/engine": "^3.6.0",
+    "gscdump": "^3.6.0"
   },
   "devDependencies": {
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "build": "obuild",