@gscdump/analysis 0.7.1 → 0.7.6

package/dist/source/index.d.mts

@@ -1,11 +1,34 @@
-import { BrowserQueryRunner, createEngine as createBrowserQuerySource } from "@gscdump/engine-wasm";
-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 { AnalyzerCapabilityError, AnalyzerRegistry } from "@gscdump/engine/analyzer";
+import { BuilderState } from "gscdump/query";
+import { AnalysisParams, AnalysisResult } from "@gscdump/engine/analysis-types";
+import { AnalysisPeriod, ComparisonPeriod } from "@gscdump/engine/period";
+import { AnalysisQuerySource, QueryRow, RowQuerySource, SqlQuerySource } 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";
+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;
+/**
+ * Permissive defaults: in-memory sources are usually test doubles, so they
+ * advertise every capability unless the test explicitly narrows them.
+ */
+declare const IN_MEMORY_DEFAULT_CAPABILITIES: PlannerCapabilities;
+interface InMemoryQuerySourceOptions {
+  queryRows: (state: BuilderState) => Promise<QueryRow[]> | QueryRow[];
+  capabilities?: PlannerCapabilities;
+}
+declare function createInMemoryQuerySource(options: InMemoryQuerySourceOptions): RowQuerySource;
+/**
+ * Domain row shapes + analysis utilities. Analyzer-call contracts
+ * (`AnalysisParams`, `AnalysisResult`, `AnalysisTool`, `num`) live in
+ * `@gscdump/engine/analysis-types`.
+ */
 type SortOrder = 'asc' | 'desc';
 /** Base search metrics */
 interface BaseMetrics {
@@ -27,208 +50,6 @@ interface PageRow extends BaseMetrics {
 interface DateRow extends BaseMetrics {
   date: string;
 }
-/**
- * Capabilities a Plan may require of its host. A dispatcher matches these
- * against a source's declared capabilities and rejects mismatches.
- */
-type Capability = 'executeSql' | 'partitionedParquet' | 'attachedTables' | 'regex' | 'windowTotals' | 'comparisonJoin';
-interface SqlExtraQuery {
-  name: string;
-  sql: string;
-  params: unknown[];
-}
-/**
- * SQL-native plan: SQL string + placeholders, with optional extra file sets
- * and follow-up queries. Mirrors the existing `AnalyzerSpec` shape but
- * renamed for clarity under the unified contract.
- */
-interface SqlPlan {
-  kind: 'sql';
-  sql: string;
-  params: unknown[];
-  current: FileSet;
-  previous?: FileSet;
-  extraFiles?: Record<string, FileSet>;
-  extraQueries?: SqlExtraQuery[];
-  /** Emits direct table refs (browser-only). Dispatcher rejects for manifest path. */
-  requiresAttachedTables?: boolean;
-}
-interface TypedRowQuery<T extends Row = Row> {
-  state: BuilderState;
-  /** Optional type tag for downstream narrowing. */
-  rowType?: (row: Row) => T;
-}
-/**
- * Row-queries plan: a named set of typed `BuilderState` queries. A portable
- * dispatcher runs each against a source's `queryRows` and hands the row
- * collection to `reduce`.
- */
-interface RowQueriesPlan {
-  kind: 'rows';
-  queries: Record<string, TypedRowQuery>;
-}
-type Plan = SqlPlan | RowQueriesPlan;
-interface ReduceContext<TRow extends Row = Row> {
-  params: AnalysisParams;
-  /** Extra SQL-query results keyed by `SqlExtraQuery.name`. */
-  extras?: Record<string, TRow[]>;
-}
-/**
- * Unified analyzer contract. `TRow` lets authors narrow from the default
- * `Row = Record<string, unknown>` to a typed row shape (e.g. `KeywordRow`)
- * when their reducer assumes specific columns exist — catches drift between
- * `build` (SELECT list) and `reduce` (column access) at compile time.
- */
-interface Analyzer<P extends AnalysisParams = AnalysisParams, R = unknown, TRow extends Row = Row> {
-  /** Stable tool id (e.g. `striking-distance`, `opportunity`). */
-  id: string;
-  /** Capabilities a host source must provide. */
-  requires: readonly Capability[];
-  /** Pure: params → plan. Snapshot-testable. */
-  build: (params: P) => Plan;
-  /** Pure: rows + context → typed result + meta. */
-  reduce: (rows: TRow[] | Record<string, TRow[]>, ctx: ReduceContext<TRow>) => {
-    results: R;
-    meta?: Record<string, unknown>;
-  };
-}
-interface AnalyzerVariants {
-  sql?: Analyzer;
-  rows?: Analyzer;
-}
-interface AnalyzerRegistry {
-  listAnalyzerIds: () => readonly string[];
-  getAnalyzerVariants: (id: string) => AnalyzerVariants | undefined;
-  resolveAnalyzer: (id: string, sourceSupportsSql: boolean) => Analyzer | undefined;
-  listAnalyzersFor: (sourceSupportsSql: boolean) => readonly Analyzer[];
-  listAnalyzerIdsFor: (source: {
-    executeSql?: unknown;
-  }) => readonly string[];
-}
-interface TypedQuery<TRow> {
-  state: BuilderState;
-  readonly __row?: TRow;
-}
-declare function typedQuery<TRow>(state: BuilderState): TypedQuery<TRow>;
-declare function queryRows<TRow = QueryRow$1>(source: AnalysisQuerySource$1, query: BuilderState | TypedQuery<TRow>): Promise<TRow[]>;
-declare function queryComparisonRows<TRow = QueryRow$1>(source: AnalysisQuerySource$1, current: BuilderState | TypedQuery<TRow>, previous: BuilderState | TypedQuery<TRow>): Promise<{
-  current: TRow[];
-  previous: TRow[];
-}>;
-declare class AnalyzerCapabilityError extends Error {
-  readonly tool: string;
-  readonly missing: readonly Capability[];
-  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
- * pushes down; comparison joins and multi-dataset queries belong to the
- * analyzer dispatcher, not the engine's builder-state query path.
- */
-declare const ENGINE_QUERY_CAPABILITIES: PlannerCapabilities;
-interface EngineQuerySourceOptions {
-  engine: StorageEngine;
-  ctx: TenantCtx;
-}
-/**
- * Wraps a storage engine as a {@link SqlQuerySource}. `queryRows` runs typed
- * builder-state queries; `executeSql` delegates to `engine.runSQL` and
- * requires `opts.fileSets` (with a `FILES` entry so the target table can be
- * resolved for partition lookup).
- */
-declare function createEngineQuerySource(options: EngineQuerySourceOptions): SqlQuerySource;
-/**
- * Convenience: wrap a storage engine + tenant ctx in a source and dispatch.
- * Equivalent to
- * `runAnalyzerFromSource(createEngineQuerySource({ engine, ctx }), params, registry)`.
- */
-declare function runAnalyzerWithEngine(deps: {
-  engine: StorageEngine;
-}, ctx: TenantCtx, params: AnalysisParams, registry: AnalyzerRegistry): Promise<AnalysisResult>;
-/**
- * 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;
-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[]>;
-/**
- * Permissive defaults: in-memory sources are usually test doubles, so they
- * advertise every capability unless the test explicitly narrows them.
- */
-declare const IN_MEMORY_DEFAULT_CAPABILITIES: PlannerCapabilities;
-interface InMemoryQuerySourceOptions {
-  queryRows: (state: BuilderState) => Promise<QueryRow[]> | QueryRow[];
-  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[];
@@ -382,14 +203,6 @@ interface SeasonalityResult {
   monthlyBreakdown: MonthlyData[];
   insufficientData: boolean;
 }
-interface AnalysisPeriod {
-  startDate: string;
-  endDate: string;
-}
-interface ComparisonPeriod {
-  current: AnalysisPeriod;
-  previous: AnalysisPeriod;
-}
 interface StrikingDistanceResult {
   keyword: string;
   page: string | null;
@@ -443,5 +256,4 @@ declare function analyzeClusteringFromSource(source: AnalysisQuerySource, period
 declare function analyzeSeasonalityFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: SeasonalityOptions): Promise<SeasonalityResult>;
 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, 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 };
+export { AnalyzerCapabilityError, type ComparisonQueryResult, type CompositeSourceOptions, IN_MEMORY_DEFAULT_CAPABILITIES, type InMemoryQuerySourceOptions, type QueryDimension, type QueryOptions, type QueryResult, analyzeBrandSegmentationFromSource, analyzeClusteringFromSource, analyzeDecayFromSource, analyzeFromSource, analyzeKeywordConcentrationFromSource, analyzeMoversFromSource, analyzeOpportunityFromSource, analyzePageConcentrationFromSource, analyzeSeasonalityFromSource, analyzeStrikingDistanceFromSource, createCompositeSource, createInMemoryQuerySource, queryAnalyticsFromSource, queryComparisonFromSource };