@gscdump/analysis 0.4.0

package/dist/source/index.d.mts

@@ -0,0 +1,427 @@
+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 { EngineConfig, SqliteQueryExecutor, createEngine as createSqliteQuerySource } from "@gscdump/engine-sqlite";
+import { Row, StorageEngine, TenantCtx } from "@gscdump/engine/contracts";
+import { AnalysisParams, AnalysisResult } from "gscdump/contracts";
+type SortOrder = 'asc' | 'desc';
+/** Base search metrics */
+interface BaseMetrics {
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+/** Keyword row from query */
+interface KeywordRow extends BaseMetrics {
+  query: string;
+  page?: string;
+}
+/** Page row from query */
+interface PageRow extends BaseMetrics {
+  page: string;
+}
+/** Date row from query */
+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>;
+/**
+ * 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;
+interface BrandSegmentationOptions {
+  /** Brand terms to match against keywords (case-insensitive) */
+  brandTerms: string[];
+  /** Minimum impressions for a keyword to be included. Default: 10 */
+  minImpressions?: number;
+}
+interface BrandSummary {
+  brandClicks: number;
+  nonBrandClicks: number;
+  brandShare: number;
+  brandImpressions: number;
+  nonBrandImpressions: number;
+}
+interface BrandSegmentationResult {
+  brand: KeywordRow[];
+  nonBrand: KeywordRow[];
+  summary: BrandSummary;
+}
+type ClusterType = 'prefix' | 'intent' | 'both';
+interface ClusteringOptions {
+  /** Minimum keywords for a cluster to be reported. Default: 2 */
+  minClusterSize?: number;
+  /** Minimum impressions for a keyword to be included. Default: 10 */
+  minImpressions?: number;
+  /** Clustering method. Default: 'both' */
+  clusterBy?: ClusterType;
+}
+interface KeywordCluster {
+  clusterName: string;
+  clusterType: 'prefix' | 'intent';
+  keywords: KeywordRow[];
+  totalClicks: number;
+  totalImpressions: number;
+  avgPosition: number;
+  keywordCount: number;
+}
+interface ClusteringResult {
+  clusters: KeywordCluster[];
+  unclustered: KeywordRow[];
+}
+type ConcentrationRiskLevel = 'low' | 'medium' | 'high';
+interface ConcentrationOptions {
+  /** Number of top items to report. Default: 10 */
+  topN?: number;
+}
+interface ConcentrationItem {
+  key: string;
+  clicks: number;
+  share: number;
+}
+interface ConcentrationResult {
+  /** Gini coefficient: 0 = equal distribution, 1 = fully concentrated */
+  giniCoefficient: number;
+  /** Herfindahl-Hirschman Index: 0-10000, >2500 = highly concentrated */
+  hhi: number;
+  /** Percentage of total clicks from top N items */
+  topNConcentration: number;
+  topNItems: ConcentrationItem[];
+  totalItems: number;
+  totalClicks: number;
+  /** Risk level derived from HHI: <1500 low, 1500-2500 medium, >2500 high */
+  riskLevel: ConcentrationRiskLevel;
+}
+type DecaySortMetric = 'lostClicks' | 'declinePercent' | 'currentClicks';
+interface DecayOptions {
+  /** Minimum clicks in previous period to consider. Default: 50 */
+  minPreviousClicks?: number;
+  /** Minimum decline percentage (0-1). Default: 0.2 (20%) */
+  threshold?: number;
+  /** Metric to sort results by. Default: lostClicks */
+  sortBy?: DecaySortMetric;
+}
+interface DecaySeriesPoint {
+  week: string;
+  clicks: number;
+  impressions: number;
+}
+interface DecayResult {
+  page: string;
+  currentClicks: number;
+  previousClicks: number;
+  lostClicks: number;
+  declinePercent: number;
+  currentPosition: number;
+  previousPosition: number;
+  positionDrop: number;
+  series?: DecaySeriesPoint[];
+}
+type MoversSortMetric = 'clicks' | 'impressions' | 'clicksChange' | 'impressionsChange' | 'positionChange';
+interface MoversOptions {
+  /** Minimum change threshold to flag. Default: 0.2 (20%) */
+  changeThreshold?: number;
+  /** Minimum impressions in recent period. Default: 50 */
+  minImpressions?: number;
+  /** Metric to sort results by. Default: clicksChange */
+  sortBy?: MoversSortMetric;
+}
+interface MoverData {
+  keyword: string;
+  page: string | null;
+  recentClicks: number;
+  recentImpressions: number;
+  recentPosition: number;
+  baselineClicks: number;
+  baselineImpressions: number;
+  baselinePosition: number;
+  clicksChange: number;
+  clicksChangePercent: number;
+  impressionsChangePercent: number;
+  positionChange: number;
+}
+interface MoversResult {
+  rising: MoverData[];
+  declining: MoverData[];
+  stable: MoverData[];
+}
+interface OpportunityFactors {
+  positionScore: number;
+  impressionScore: number;
+  ctrGapScore: number;
+}
+interface OpportunityResult {
+  keyword: string;
+  page: string | null;
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+  opportunityScore: number;
+  potentialClicks: number;
+  factors: OpportunityFactors;
+}
+type SeasonalityMetric = 'clicks' | 'impressions';
+interface SeasonalityOptions {
+  /** Metric to analyze for seasonality. Default: clicks */
+  metric?: SeasonalityMetric;
+}
+interface MonthlyData {
+  month: string;
+  value: number;
+  vsAverage: number;
+  isPeak: boolean;
+  isTrough: boolean;
+}
+interface SeasonalityResult {
+  hasSeasonality: boolean;
+  /** Coefficient of variation: std dev / mean. Higher = more seasonal. */
+  strength: number;
+  peakMonths: string[];
+  troughMonths: string[];
+  monthlyBreakdown: MonthlyData[];
+  insufficientData: boolean;
+}
+interface AnalysisPeriod {
+  startDate: string;
+  endDate: string;
+}
+interface ComparisonPeriod {
+  current: AnalysisPeriod;
+  previous: AnalysisPeriod;
+}
+interface StrikingDistanceResult {
+  keyword: string;
+  page: string | null;
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+  /** Estimated clicks at ~15% CTR (the average for positions 1–3). */
+  potentialClicks: number;
+}
+type StrikingDistanceSortMetric = 'clicks' | 'impressions' | 'ctr' | 'position' | 'potentialClicks';
+interface StrikingDistanceOptions {
+  /** Minimum position (inclusive). Default: 4 */
+  minPosition?: number;
+  /** Maximum position (inclusive). Default: 20 */
+  maxPosition?: number;
+  /** Minimum impressions. Default: 100 */
+  minImpressions?: number;
+  /** Maximum CTR (queries with low CTR have more potential). Default: 0.05 (5%) */
+  maxCtr?: number;
+  /** Sort metric. Default: potentialClicks */
+  sortBy?: StrikingDistanceSortMetric;
+  /** Sort order. Default: desc */
+  sortOrder?: SortOrder;
+}
+type QueryDimension = 'keywords' | 'pages' | 'dates';
+interface QueryOptions {
+  dimension?: QueryDimension;
+  limit?: number;
+}
+interface QueryResult {
+  keywords: KeywordRow[];
+  pages: PageRow[];
+  dates: DateRow[];
+}
+interface ComparisonQueryResult {
+  current: QueryResult;
+  previous: QueryResult;
+}
+interface OpportunityOptions {
+  minImpressions?: number;
+}
+declare function queryAnalyticsFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: QueryOptions): Promise<QueryResult>;
+declare function queryComparisonFromSource(source: AnalysisQuerySource, periods: ComparisonPeriod, options?: QueryOptions): Promise<ComparisonQueryResult>;
+declare function analyzeStrikingDistanceFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: StrikingDistanceOptions): Promise<StrikingDistanceResult[]>;
+declare function analyzeOpportunityFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: OpportunityOptions): Promise<OpportunityResult[]>;
+declare function analyzeBrandSegmentationFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options: BrandSegmentationOptions): Promise<BrandSegmentationResult>;
+declare function analyzePageConcentrationFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: ConcentrationOptions): Promise<ConcentrationResult>;
+declare function analyzeKeywordConcentrationFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: ConcentrationOptions): Promise<ConcentrationResult>;
+declare function analyzeClusteringFromSource(source: AnalysisQuerySource, period: AnalysisPeriod, options?: ClusteringOptions): Promise<ClusteringResult>;
+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, 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 };