@gscdump/analysis 0.6.2 → 0.6.3

package/dist/index.mjs

@@ -2579,53 +2579,6 @@ const WHITESPACE_RE = /\s+/g;
 function normalizeQuery(query) {
 	return query.toLowerCase().replace(SEPARATOR_RE, " ").replace(WHITESPACE_RE, " ").trim().split(" ").filter(Boolean).map((token) => SYNONYMS[token] ?? token).filter(Boolean).map(depluralize).sort().join(" ");
 }
-function isMetricDimension$2(dim) {
-	return [
-		"clicks",
-		"impressions",
-		"ctr",
-		"position"
-	].includes(dim);
-}
-const ENGINE_SOURCE_CAPABILITIES = {
-	regex: true,
-	multiDataset: false,
-	comparisonJoin: false,
-	windowTotals: false,
-	fileSets: true,
-	localSource: true
-};
-function createEngineQuerySource(options) {
-	const { engine, ctx } = options;
-	return {
-		name: "engine",
-		capabilities: ENGINE_SOURCE_CAPABILITIES,
-		async queryRows(state) {
-			const filterDims = getFilterDimensions(state.filter, isMetricDimension$2);
-			assertDimensionsSupported([...state.dimensions, ...filterDims], "stored", "engine query source");
-			if (state.dimensions.includes("queryCanonical") || filterDims.includes("queryCanonical")) throw new Error("engine query source does not support queryCanonical; use browser/sqlite query sources for derived dimensions");
-			return (await engine.query(ctx, state)).rows;
-		},
-		async executeSql(sql, params, opts) {
-			const fileSets = opts?.fileSets;
-			if (!fileSets?.FILES) throw new Error("engine query source: executeSql requires opts.fileSets with a FILES entry");
-			const { rows } = await engine.runSQL({
-				ctx,
-				table: fileSets.FILES.table,
-				fileSets,
-				sql,
-				params: params ?? []
-			});
-			return rows;
-		}
-	};
-}
-async function runAnalyzerWithEngine(deps, ctx, params, registry) {
-	return runAnalyzerFromSource(createEngineQuerySource({
-		engine: deps.engine,
-		ctx
-	}), params, registry);
-}
 async function collectRows(gen) {
 	const out = [];
 	for await (const batch of gen) out.push(...batch);
@@ -2637,11 +2590,11 @@ const METRIC_NAMES = [
 	"ctr",
 	"position"
 ];
-function isMetricDimension$1(dim) {
+function isMetricDimension$2(dim) {
 	return METRIC_NAMES.includes(dim);
 }
 function applyBuilderStatePostProcessing(rows, state) {
-	const dimensionFilters = getDimensionFilters(state.filter, isMetricDimension$1);
+	const dimensionFilters = getDimensionFilters(state.filter, isMetricDimension$2);
 	const metricFilters = extractMetricFilters(state.filter);
 	const specialFilters = extractSpecialOperatorFilters(state.filter);
 	const ordered = [...rows.filter((row) => {
@@ -2668,7 +2621,7 @@ const GSC_API_CAPABILITIES = {
 	comparisonJoin: false,
 	windowTotals: false
 };
-function isMetricDimension(dim) {
+function isMetricDimension$1(dim) {
 	return [
 		"clicks",
 		"impressions",
@@ -2686,12 +2639,59 @@ function createGscApiQuerySource(options) {
 		capabilities: GSC_API_CAPABILITIES,
 		async queryRows(state) {
 			buildLogicalPlan(state, GSC_API_CAPABILITIES);
-			const filterDims = getFilterDimensions(state.filter, isMetricDimension);
+			const filterDims = getFilterDimensions(state.filter, isMetricDimension$1);
 			assertDimensionsSupported([...state.dimensions, ...filterDims], "api", "gsc-api query source");
 			return applyBuilderStatePostProcessing(await collectRows(client.query(siteUrl, builderFromState(state))), state);
 		}
 	};
 }
+function isMetricDimension(dim) {
+	return [
+		"clicks",
+		"impressions",
+		"ctr",
+		"position"
+	].includes(dim);
+}
+const ENGINE_SOURCE_CAPABILITIES = {
+	regex: true,
+	multiDataset: false,
+	comparisonJoin: false,
+	windowTotals: false,
+	fileSets: true,
+	localSource: true
+};
+function createEngineQuerySource(options) {
+	const { engine, ctx } = options;
+	return {
+		name: "engine",
+		capabilities: ENGINE_SOURCE_CAPABILITIES,
+		async queryRows(state) {
+			const filterDims = getFilterDimensions(state.filter, isMetricDimension);
+			assertDimensionsSupported([...state.dimensions, ...filterDims], "stored", "engine query source");
+			if (state.dimensions.includes("queryCanonical") || filterDims.includes("queryCanonical")) throw new Error("engine query source does not support queryCanonical; use browser/sqlite query sources for derived dimensions");
+			return (await engine.query(ctx, state)).rows;
+		},
+		async executeSql(sql, params, opts) {
+			const fileSets = opts?.fileSets;
+			if (!fileSets?.FILES) throw new Error("engine query source: executeSql requires opts.fileSets with a FILES entry");
+			const { rows } = await engine.runSQL({
+				ctx,
+				table: fileSets.FILES.table,
+				fileSets,
+				sql,
+				params: params ?? []
+			});
+			return rows;
+		}
+	};
+}
+async function runAnalyzerWithEngine(deps, ctx, params, registry) {
+	return runAnalyzerFromSource(createEngineQuerySource({
+		engine: deps.engine,
+		ctx
+	}), params, registry);
+}
 const IN_MEMORY_DEFAULT_CAPABILITIES = {
 	regex: true,
 	multiDataset: true,

package/dist/source/index.d.mts

@@ -1,8 +1,8 @@
 import { BrowserQueryRunner, createEngine as createBrowserQuerySource } from "@gscdump/engine-wasm";
-import { AnalysisQuerySource, AnalysisQuerySource as AnalysisQuerySource$1, FileSet, QueryRow, QueryRow as QueryRow$1, RowQuerySource, SourceCapabilities, SqlQuerySource, isSqlQuerySource } from "@gscdump/engine/resolver";
-import { PlannerCapabilities } from "gscdump/query/plan";
 import { BuilderState, Column, Dimension } from "gscdump/query";
 import { GoogleSearchConsoleClient } from "gscdump";
+import { AnalysisQuerySource, AnalysisQuerySource as AnalysisQuerySource$1, FileSet, QueryRow, QueryRow as QueryRow$1, RowQuerySource, SourceCapabilities, SqlQuerySource, isSqlQuerySource } from "@gscdump/engine/resolver";
+import { PlannerCapabilities } from "gscdump/query/plan";
 import { EngineConfig, SqliteQueryExecutor, createEngine as createSqliteQuerySource } from "@gscdump/engine-sqlite";
 import { Row, StorageEngine, TenantCtx } from "@gscdump/engine/contracts";
 import { AnalysisParams, AnalysisResult } from "gscdump/contracts";
@@ -121,6 +121,15 @@ declare class AnalyzerCapabilityError extends Error {
   constructor(tool: string, missing: readonly Capability[]);
 }
 declare function analyzeFromSource(source: AnalysisQuerySource, params: AnalysisParams, registry: AnalyzerRegistry): Promise<AnalysisResult>;
+interface CompositeSourceOptions {
+  engine: SqlQuerySource;
+  live: AnalysisQuerySource;
+  site: {
+    oldestDateSynced: string | null;
+    newestDateSynced: string | null;
+  };
+}
+declare function createCompositeSource(opts: CompositeSourceOptions): SqlQuerySource;
 /**
  * Capabilities the engine query path honors. Matches what the DuckDB compiler
  * passes to {@link buildLogicalPlan} (see `gscdump/analytics/compiler`): regex
@@ -209,6 +218,17 @@ interface InMemoryQuerySourceOptions {
   capabilities?: PlannerCapabilities;
 }
 declare function createInMemoryQuerySource(options: InMemoryQuerySourceOptions): RowQuerySource;
+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;
 interface BrandSegmentationOptions {
   /** Brand terms to match against keywords (case-insensitive) */
   brandTerms: string[];
@@ -424,4 +444,4 @@ declare function analyzeSeasonalityFromSource(source: AnalysisQuerySource, perio
 declare function analyzeDecayFromSource(source: AnalysisQuerySource, periods: ComparisonPeriod, options?: DecayOptions): Promise<DecayResult[]>;
 declare function analyzeMoversFromSource(source: AnalysisQuerySource, periods: ComparisonPeriod, options?: MoversOptions): Promise<MoversResult>;
 type SqliteQuerySourceOptions = EngineConfig;
-export { type AnalysisQuerySource, AnalyzerCapabilityError, type BrowserQueryRunner, type ComparisonQueryResult, ENGINE_QUERY_CAPABILITIES, type EngineQuerySourceOptions, type FetchTopNOptions, GSC_API_CAPABILITIES, type GscApiQuerySourceOptions, type GscDailyRow, type GscRange, type GscTopNRow, IN_MEMORY_DEFAULT_CAPABILITIES, type InMemoryQuerySourceOptions, type QueryDimension, type QueryOptions, type QueryResult, type QueryRow, type RowQuerySource, type SourceCapabilities, type SqlQuerySource, type SqliteQueryExecutor, type SqliteQuerySourceOptions, type TypedQuery, analyzeBrandSegmentationFromSource, analyzeClusteringFromSource, analyzeDecayFromSource, analyzeFromSource, analyzeKeywordConcentrationFromSource, analyzeMoversFromSource, analyzeOpportunityFromSource, analyzePageConcentrationFromSource, analyzeSeasonalityFromSource, analyzeStrikingDistanceFromSource, collectRows as collectGscRows, createBrowserQuerySource, createEngineQuerySource, createGscApiQuerySource, createInMemoryQuerySource, createSqliteQuerySource, fetchGscDaily, fetchGscTopN, isSqlQuerySource, queryAnalyticsFromSource, queryComparisonFromSource, queryComparisonRows, queryRows, runAnalyzerWithEngine, typedQuery };
+export { type AnalysisQuerySource, AnalyzerCapabilityError, type BrowserQueryRunner, type ComparisonQueryResult, type CompositeSourceOptions, type CreateLiveGscSourceOptions, ENGINE_QUERY_CAPABILITIES, type EngineQuerySourceOptions, type FetchTopNOptions, GSC_API_CAPABILITIES, type GscApiQuerySourceOptions, type GscDailyRow, type GscRange, type GscTopNRow, IN_MEMORY_DEFAULT_CAPABILITIES, type InMemoryQuerySourceOptions, type QueryDimension, type QueryOptions, type QueryResult, type QueryRow, type RowQuerySource, type SourceCapabilities, type SqlQuerySource, type SqliteQueryExecutor, type SqliteQuerySourceOptions, type TypedQuery, analyzeBrandSegmentationFromSource, analyzeClusteringFromSource, analyzeDecayFromSource, analyzeFromSource, analyzeKeywordConcentrationFromSource, analyzeMoversFromSource, analyzeOpportunityFromSource, analyzePageConcentrationFromSource, analyzeSeasonalityFromSource, analyzeStrikingDistanceFromSource, canProxyToGsc, collectRows as collectGscRows, createBrowserQuerySource, createCompositeSource, createEngineQuerySource, createGscApiQuerySource, createInMemoryQuerySource, createLiveGscSource, createSqliteQuerySource, fetchGscDaily, fetchGscTopN, isSqlQuerySource, queryAnalyticsFromSource, queryComparisonFromSource, queryComparisonRows, queryRows, runAnalyzerWithEngine, typedQuery };

package/dist/source/index.mjs

@@ -1,10 +1,10 @@
 import { createEngine as createBrowserQuerySource } from "@gscdump/engine-wasm";
+import { between, clicks, date, extractDateRange, extractMetricFilters, extractSpecialOperatorFilters, gsc, page, query } from "gscdump/query";
+import { daysAgo, googleSearchConsole } from "gscdump";
 import { assertDimensionsSupported, getDimensionFilters, getFilterDimensions, isSqlQuerySource, matchesDimensionFilter, matchesMetricFilter, matchesTopLevelPage, metricValue } from "@gscdump/engine/resolver";
 import { buildLogicalPlan } from "gscdump/query/plan";
-import { between, clicks, date, extractMetricFilters, extractSpecialOperatorFilters, gsc, page, query } from "gscdump/query";
 import { enumeratePartitions } from "@gscdump/engine/planner";
 import { METRIC_EXPR } from "@gscdump/engine/sql-fragments";
-import { daysAgo } from "gscdump";
 import { createEngine as createSqliteQuerySource } from "@gscdump/engine-sqlite";
 var AnalyzerCapabilityError = class extends Error {
 	constructor(tool, missing) {
@@ -83,56 +83,6 @@ async function runSqlPlanAgainstSource(source, analyzer, plan, params) {
 async function analyzeFromSource(source, params, registry) {
 	return runAnalyzerFromSource(source, params, registry);
 }
-function isMetricDimension$2(dim) {
-	return [
-		"clicks",
-		"impressions",
-		"ctr",
-		"position"
-	].includes(dim);
-}
-const ENGINE_QUERY_CAPABILITIES = {
-	regex: true,
-	multiDataset: false,
-	comparisonJoin: false,
-	windowTotals: false
-};
-const ENGINE_SOURCE_CAPABILITIES = {
-	...ENGINE_QUERY_CAPABILITIES,
-	fileSets: true,
-	localSource: true
-};
-function createEngineQuerySource(options) {
-	const { engine, ctx } = options;
-	return {
-		name: "engine",
-		capabilities: ENGINE_SOURCE_CAPABILITIES,
-		async queryRows(state) {
-			const filterDims = getFilterDimensions(state.filter, isMetricDimension$2);
-			assertDimensionsSupported([...state.dimensions, ...filterDims], "stored", "engine query source");
-			if (state.dimensions.includes("queryCanonical") || filterDims.includes("queryCanonical")) throw new Error("engine query source does not support queryCanonical; use browser/sqlite query sources for derived dimensions");
-			return (await engine.query(ctx, state)).rows;
-		},
-		async executeSql(sql, params, opts) {
-			const fileSets = opts?.fileSets;
-			if (!fileSets?.FILES) throw new Error("engine query source: executeSql requires opts.fileSets with a FILES entry");
-			const { rows } = await engine.runSQL({
-				ctx,
-				table: fileSets.FILES.table,
-				fileSets,
-				sql,
-				params: params ?? []
-			});
-			return rows;
-		}
-	};
-}
-async function runAnalyzerWithEngine(deps, ctx, params, registry) {
-	return runAnalyzerFromSource(createEngineQuerySource({
-		engine: deps.engine,
-		ctx
-	}), params, registry);
-}
 async function collectRows(gen) {
 	const out = [];
 	for await (const batch of gen) out.push(...batch);
@@ -181,11 +131,11 @@ const METRIC_NAMES = [
 	"ctr",
 	"position"
 ];
-function isMetricDimension$1(dim) {
+function isMetricDimension$2(dim) {
 	return METRIC_NAMES.includes(dim);
 }
 function applyBuilderStatePostProcessing(rows, state) {
-	const dimensionFilters = getDimensionFilters(state.filter, isMetricDimension$1);
+	const dimensionFilters = getDimensionFilters(state.filter, isMetricDimension$2);
 	const metricFilters = extractMetricFilters(state.filter);
 	const specialFilters = extractSpecialOperatorFilters(state.filter);
 	const ordered = [...rows.filter((row) => {
@@ -212,7 +162,7 @@ const GSC_API_CAPABILITIES = {
 	comparisonJoin: false,
 	windowTotals: false
 };
-function isMetricDimension(dim) {
+function isMetricDimension$1(dim) {
 	return [
 		"clicks",
 		"impressions",
@@ -230,12 +180,107 @@ function createGscApiQuerySource(options) {
 		capabilities: GSC_API_CAPABILITIES,
 		async queryRows(state) {
 			buildLogicalPlan(state, GSC_API_CAPABILITIES);
-			const filterDims = getFilterDimensions(state.filter, isMetricDimension);
+			const filterDims = getFilterDimensions(state.filter, isMetricDimension$1);
 			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);
+		}
+	};
+}
+function createCompositeSource(opts) {
+	const { engine, live, site } = opts;
+	function rangeCovered(state) {
+		const { startDate, endDate } = extractDateRange(state.filter);
+		return !!(startDate && endDate && site.oldestDateSynced && site.newestDateSynced && startDate >= site.oldestDateSynced && endDate <= site.newestDateSynced);
+	}
+	return {
+		name: "composite-engine-live",
+		capabilities: engine.capabilities,
+		async queryRows(state) {
+			if (!rangeCovered(state) && canProxyToGsc(state)) return live.queryRows(state);
+			return engine.queryRows(state);
+		},
+		executeSql: engine.executeSql
+	};
+}
+function isMetricDimension(dim) {
+	return [
+		"clicks",
+		"impressions",
+		"ctr",
+		"position"
+	].includes(dim);
+}
+const ENGINE_QUERY_CAPABILITIES = {
+	regex: true,
+	multiDataset: false,
+	comparisonJoin: false,
+	windowTotals: false
+};
+const ENGINE_SOURCE_CAPABILITIES = {
+	...ENGINE_QUERY_CAPABILITIES,
+	fileSets: true,
+	localSource: true
+};
+function createEngineQuerySource(options) {
+	const { engine, ctx } = options;
+	return {
+		name: "engine",
+		capabilities: ENGINE_SOURCE_CAPABILITIES,
+		async queryRows(state) {
+			const filterDims = getFilterDimensions(state.filter, isMetricDimension);
+			assertDimensionsSupported([...state.dimensions, ...filterDims], "stored", "engine query source");
+			if (state.dimensions.includes("queryCanonical") || filterDims.includes("queryCanonical")) throw new Error("engine query source does not support queryCanonical; use browser/sqlite query sources for derived dimensions");
+			return (await engine.query(ctx, state)).rows;
+		},
+		async executeSql(sql, params, opts) {
+			const fileSets = opts?.fileSets;
+			if (!fileSets?.FILES) throw new Error("engine query source: executeSql requires opts.fileSets with a FILES entry");
+			const { rows } = await engine.runSQL({
+				ctx,
+				table: fileSets.FILES.table,
+				fileSets,
+				sql,
+				params: params ?? []
+			});
+			return rows;
+		}
+	};
+}
+async function runAnalyzerWithEngine(deps, ctx, params, registry) {
+	return runAnalyzerFromSource(createEngineQuerySource({
+		engine: deps.engine,
+		ctx
+	}), params, registry);
+}
 const IN_MEMORY_DEFAULT_CAPABILITIES = {
 	regex: true,
 	multiDataset: true,
@@ -1862,4 +1907,4 @@ async function analyzeDecayFromSource(source, periods, options) {
 async function analyzeMoversFromSource(source, periods, options) {
 	return runPortableAnalyzer(source, PORTABLE_ANALYZERS.movers, periods, options);
 }
-export { AnalyzerCapabilityError, ENGINE_QUERY_CAPABILITIES, GSC_API_CAPABILITIES, IN_MEMORY_DEFAULT_CAPABILITIES, analyzeBrandSegmentationFromSource, analyzeClusteringFromSource, analyzeDecayFromSource, analyzeFromSource, analyzeKeywordConcentrationFromSource, analyzeMoversFromSource, analyzeOpportunityFromSource, analyzePageConcentrationFromSource, analyzeSeasonalityFromSource, analyzeStrikingDistanceFromSource, collectRows as collectGscRows, createBrowserQuerySource, createEngineQuerySource, createGscApiQuerySource, createInMemoryQuerySource, createSqliteQuerySource, fetchGscDaily, fetchGscTopN, isSqlQuerySource, queryAnalyticsFromSource, queryComparisonFromSource, queryComparisonRows, queryRows, runAnalyzerWithEngine, typedQuery };
+export { AnalyzerCapabilityError, ENGINE_QUERY_CAPABILITIES, GSC_API_CAPABILITIES, IN_MEMORY_DEFAULT_CAPABILITIES, analyzeBrandSegmentationFromSource, analyzeClusteringFromSource, analyzeDecayFromSource, analyzeFromSource, analyzeKeywordConcentrationFromSource, analyzeMoversFromSource, analyzeOpportunityFromSource, analyzePageConcentrationFromSource, analyzeSeasonalityFromSource, analyzeStrikingDistanceFromSource, canProxyToGsc, collectRows as collectGscRows, createBrowserQuerySource, createCompositeSource, createEngineQuerySource, createGscApiQuerySource, createInMemoryQuerySource, createLiveGscSource, createSqliteQuerySource, fetchGscDaily, fetchGscTopN, isSqlQuerySource, queryAnalyticsFromSource, queryComparisonFromSource, queryComparisonRows, queryRows, runAnalyzerWithEngine, typedQuery };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/analysis",
   "type": "module",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "GSC analyzers — striking-distance, opportunity, movers, decay, brand, clustering, concentration, seasonality. Pure row-based + DuckDB-native.",
   "author": {
     "name": "Harlan Wilton",
@@ -68,11 +68,11 @@
   },
   "dependencies": {
     "drizzle-orm": "^0.45.2",
-    "@gscdump/engine-duckdb-node": "0.6.2",
-    "@gscdump/engine": "0.6.2",
-    "@gscdump/engine-sqlite": "0.6.2",
-    "@gscdump/engine-wasm": "0.6.2",
-    "gscdump": "0.6.2"
+    "@gscdump/engine-duckdb-node": "0.6.3",
+    "@gscdump/engine-sqlite": "0.6.3",
+    "@gscdump/engine-wasm": "0.6.3",
+    "gscdump": "0.6.3",
+    "@gscdump/engine": "0.6.3"
   },
   "devDependencies": {
     "vitest": "^4.1.5"