@gscdump/analysis 0.9.2 → 0.11.0

package/dist/index.d.mts

@@ -1,10 +1,9 @@
-import { AnalysisParams, AnalysisParams as AnalysisParams$1, AnalysisResult, AnalysisResult as AnalysisResult$1, AnalysisTool, num } from "@gscdump/engine/analysis-types";
 import * as _$_gscdump_engine_analyzer0 from "@gscdump/engine/analyzer";
-import { Analyzer, Analyzer as Analyzer$1, AnalyzerCapabilityError, AnalyzerRegistry, AnalyzerRegistry as AnalyzerRegistry$1, AnalyzerRegistryInit, AnalyzerVariants, Capability, DefineAnalyzerOptions, DefinedAnalyzer, Plan, ReduceContext, ReduceCtx, Reducer, RowQueriesPlan, SqlExtraQuery, SqlPlan, SqlPlanSpec, TypedRowQuery, createAnalyzerRegistry, defineAnalyzer, runAnalyzerFromSource } from "@gscdump/engine/analyzer";
-import { AnalysisPeriod, AnalysisPeriod as AnalysisPeriod$1, ComparisonMode, ComparisonPeriod, ComparisonPeriod as ComparisonPeriod$1, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, padTimeseries, periodOf, resolveWindow, windowToComparisonPeriod, windowToPeriod } from "@gscdump/engine/period";
+import { Analyzer, Analyzer as Analyzer$1, AnalyzerCapabilityError, AnalyzerRegistry, AnalyzerRegistry as AnalyzerRegistry$1, AnalyzerRegistryInit, AnalyzerVariants, DefineAnalyzerOptions, DefinedAnalyzer, Plan, ReduceContext, ReduceCtx, Reducer, RequiredCapability, RowQueriesPlan, SqlExtraQuery, SqlPlan, SqlPlanSpec, TypedRowQuery, createAnalyzerRegistry, defineAnalyzer, runAnalyzerFromSource } from "@gscdump/engine/analyzer";
+import { AnalysisPeriod, ComparisonMode, ComparisonPeriod, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, padTimeseries, periodOf, resolveWindow, windowToComparisonPeriod, windowToPeriod } from "@gscdump/engine/period";
+import { AnalysisParams, AnalysisParams as AnalysisParams$1, AnalysisResult, AnalysisResult as AnalysisResult$1, AnalysisTool, num } from "@gscdump/engine/analysis-types";
 import { BuilderState } from "gscdump/query";
-import { AttachedTableRunner, AttachedTableRunner as AnalyzerRunner, AttachedTableSourceOptions, AttachedTableSourceOptions as BrowserAnalyzeOptions, ENGINE_QUERY_CAPABILITIES, EngineQuerySourceOptions, TypedQuery, createEngineQuerySource, queryComparisonRows, queryRows, rewriteForTableSource, runAnalyzerWithEngine, typedQuery } from "@gscdump/engine/source";
-import { AnalysisQuerySource, AnalysisQuerySource as AnalysisQuerySource$1, ExecuteSqlOptions, FileSet, QueryRow, QueryRow as QueryRow$1, RowQuerySource, RowQuerySource as RowQuerySource$1, SourceCapabilities, SqlQuerySource, SqlQuerySource as SqlQuerySource$1, isSqlQuerySource } from "@gscdump/engine/resolver";
+import { AnalysisQuerySource, AnalysisQuerySource as AnalysisQuerySource$1, AnalysisSourceKind, AttachedTableRunner, AttachedTableRunner as AnalyzerRunner, AttachedTableSourceOptions, AttachedTableSourceOptions as BrowserAnalyzeOptions, ENGINE_QUERY_CAPABILITIES, EngineQuerySourceOptions, ExecuteSqlOptions, FileSet, QueryRow, QueryRow as QueryRow$1, SourceCapabilities, TypedQuery, createEngineQuerySource, queryComparisonRows, queryRows, rewriteForTableSource, runAnalyzerWithEngine, typedQuery } from "@gscdump/engine/source";
 import * as _$_gscdump_engine_report0 from "@gscdump/engine/report";
 import { DefineReportOptions, DefinedReport, DefinedReport as DefinedReport$1, ReportAction, ReportContext, ReportContext as ReportContext$1, ReportFinding, ReportParams, ReportPlanStep, ReportResult, ReportResult as ReportResult$1, ReportSection } from "@gscdump/engine/report";
 import { PlannerCapabilities } from "gscdump/query/plan";
@@ -335,6 +334,40 @@ interface SeasonalityResult {
  * variation. Re-exported from `@gscdump/analysis` for portable callers.
  */
 declare function analyzeSeasonality(dates: DateRow[], options?: SeasonalityOptions): SeasonalityResult;
+/**
+ * Unified `striking-distance` analyzer. Spike for the `defineAnalyzer`
+ * pattern: one file owns the SQL plan, the row plan, the typed `InputRow`
+ * contract, and the shared reducer.
+ *
+ * SQL and row plans both emit rows matching `StrikingDistanceInputRow`.
+ * Filtering (`minPosition`/`maxPosition`/`minImpressions`/`maxCtr`),
+ * derivation (`potentialClicks`), and sorting all live in the reducer, so
+ * drift between plans cannot silently change results. A SQL-side `LIMIT`
+ * push-down can be added later as an optional optimization, but the
+ * correctness contract stays with the reducer.
+ */
+/**
+ * Row shape both plans produce. Field names match GSC's native columns so
+ * the row-source path needs no rename step; the SQL plan aliases `url → page`.
+ */
+interface StrikingDistanceInputRow {
+  query: string;
+  page: string | null;
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+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;
+}
 /**
  * `zero-click` — high impressions, low CTR, good ranking. SQL groups by
  * (query, url) and applies HAVING/WHERE pushdown; row reducer dedupes to the
@@ -349,12 +382,12 @@ interface ZeroClickResult {
   ctr: number;
   position: number;
 }
-declare function analyzeInBrowser(runner: AttachedTableRunner, opts: AttachedTableSourceOptions, params: AnalysisParams$1): Promise<AnalysisResult$1>;
+declare function analyzeInBrowser(runner: AttachedTableRunner, opts: AttachedTableSourceOptions, params: AnalysisParams$1, registry: AnalyzerRegistry$1): Promise<AnalysisResult$1>;
 /**
- * Default analyzer registry built from every in-tree analyzer: row analyzers
- * plus DuckDB SQL analyzers. Convenience for callers who don't care about
- * bundle size; edge / browser consumers should compose their own narrower
- * registry via `createAnalyzerRegistry`.
+ * Default analyzer registry built from every in-tree analyzer. Convenience
+ * for callers who don't care about bundle size; edge / browser consumers
+ * should compose their own narrower registry via `createAnalyzerRegistry`
+ * with the flat `ROW_ANALYZERS` / `SQL_ANALYZERS` arrays.
  */
 declare const defaultAnalyzerRegistry: _$_gscdump_engine_analyzer0.AnalyzerRegistry;
 /**
@@ -400,16 +433,16 @@ interface DryRunReportResult {
  * Useful right now only as an "is this report wired up correctly?" check.
  */
 declare function dryRunReport<P extends ReportParams = ReportParams>(report: DefinedReport$1<P>, ctx: ReportContext$1<P>): Promise<DryRunReportResult>;
-declare function analyzeFromSource(source: AnalysisQuerySource$1, params: AnalysisParams$1, registry: AnalyzerRegistry$1): Promise<AnalysisResult$1>;
+interface SyncedRange {
+  oldestDateSynced: string | null;
+  newestDateSynced: string | null;
+}
 interface CompositeSourceOptions {
-  engine: SqlQuerySource$1;
+  engine: AnalysisQuerySource$1;
   live: AnalysisQuerySource$1;
-  site: {
-    oldestDateSynced: string | null;
-    newestDateSynced: string | null;
-  };
+  site: SyncedRange;
 }
-declare function createCompositeSource(opts: CompositeSourceOptions): SqlQuerySource$1;
+declare function createCompositeSource(opts: CompositeSourceOptions): AnalysisQuerySource$1;
 /**
  * Permissive defaults: in-memory sources are usually test doubles, so they
  * advertise every capability unless the test explicitly narrows them.
@@ -419,64 +452,6 @@ interface InMemoryQuerySourceOptions {
   queryRows: (state: BuilderState) => Promise<QueryRow$1[]> | QueryRow$1[];
   capabilities?: PlannerCapabilities;
 }
-declare function createInMemoryQuerySource(options: InMemoryQuerySourceOptions): RowQuerySource$1;
-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;
-}
-/**
- * Finds striking distance keywords - high impressions, low CTR, position 4-20.
- * These are "quick wins" that could gain significant traffic with small ranking improvements.
- */
-declare function analyzeStrikingDistance(keywords: KeywordRow[], options?: StrikingDistanceOptions): StrikingDistanceResult[];
-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$1, period: AnalysisPeriod$1, options?: QueryOptions): Promise<QueryResult>;
-declare function queryComparisonFromSource(source: AnalysisQuerySource$1, periods: ComparisonPeriod$1, options?: QueryOptions): Promise<ComparisonQueryResult>;
-declare function analyzeStrikingDistanceFromSource(source: AnalysisQuerySource$1, period: AnalysisPeriod$1, options?: StrikingDistanceOptions): Promise<StrikingDistanceResult[]>;
-declare function analyzeOpportunityFromSource(source: AnalysisQuerySource$1, period: AnalysisPeriod$1, options?: OpportunityOptions): Promise<OpportunityResult[]>;
-declare function analyzeBrandSegmentationFromSource(source: AnalysisQuerySource$1, period: AnalysisPeriod$1, options: BrandSegmentationOptions): Promise<BrandSegmentationResult>;
-declare function analyzePageConcentrationFromSource(source: AnalysisQuerySource$1, period: AnalysisPeriod$1, options?: ConcentrationOptions): Promise<ConcentrationResult>;
-declare function analyzeKeywordConcentrationFromSource(source: AnalysisQuerySource$1, period: AnalysisPeriod$1, options?: ConcentrationOptions): Promise<ConcentrationResult>;
-declare function analyzeClusteringFromSource(source: AnalysisQuerySource$1, period: AnalysisPeriod$1, options?: ClusteringOptions): Promise<ClusteringResult>;
-declare function analyzeSeasonalityFromSource(source: AnalysisQuerySource$1, period: AnalysisPeriod$1, options?: SeasonalityOptions): Promise<SeasonalityResult>;
-declare function analyzeDecayFromSource(source: AnalysisQuerySource$1, periods: ComparisonPeriod$1, options?: DecayOptions): Promise<DecayResult[]>;
-declare function analyzeMoversFromSource(source: AnalysisQuerySource$1, periods: ComparisonPeriod$1, options?: MoversOptions): Promise<MoversResult>;
+declare function createInMemoryQuerySource(options: InMemoryQuerySourceOptions): AnalysisQuerySource$1;
 declare const SQL_ANALYZERS: readonly Analyzer$1[];
-export { type ActionPriorityResult, type ActionPrioritySourceState, type ActionPrioritySourceStatus, type ActionSource, type AnalysisParams, type AnalysisPeriod, type AnalysisQuerySource, type AnalysisResult, type AnalysisTool, type Analyzer, AnalyzerCapabilityError, type AnalyzerRegistry, type AnalyzerRegistryInit, type AnalyzerRunner, type AnalyzerVariants, type BaseMetrics, type BrandSegmentationOptions, type BrandSegmentationResult, type BrandSummary, type BrowserAnalyzeOptions, type CannibalizationCompetitor, type CannibalizationEvent, type CannibalizationOptions, type CannibalizationPage, type CannibalizationResult, type CannibalizationSortMetric, type Capability, type ClusterType, type ClusteringOptions, type ClusteringResult, type ComparisonMode, type ComparisonPeriod, type ComparisonQueryResult, type CompositeSourceOptions, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, DEFAULT_PRIORITY_SOURCES, type DateRow, type DecayInput, type DecayOptions, type DecayResult, type DecaySeriesPoint, type DecaySortMetric, type DefineAnalyzerOptions, type DefineReportOptions, type DefinedAnalyzer, type DefinedReport, type DryRunReportResult, ENGINE_QUERY_CAPABILITIES, type Effort, type EngineQuerySourceOptions, type ExecuteSqlOptions, type FileSet, type FormatReportOptions, IN_MEMORY_DEFAULT_CAPABILITIES, type InMemoryQuerySourceOptions, type KeywordCluster, type KeywordRow, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversSortMetric, type OpportunityResult, type PadTimeseriesOptions, type PageRow, type Plan, type PriorityAction, type QueryDimension, type QueryOptions, type QueryPageRow, type QueryResult, type QueryRow, REPORTS, ROW_ANALYZERS, type ReduceContext, type ReduceCtx, type Reducer, type ReportAction, type ReportContext, type ReportFinding, type ReportPlanStep, type ReportResult, type ReportSection, type ResolveWindowOptions, type ResolvedWindow, type RowQueriesPlan, type RowQuerySource, type RunReportOptions, SQL_ANALYZERS, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type SortOrder, type SourceCapabilities, type SqlExtraQuery, type SqlPlan, type SqlPlanSpec, type SqlQuerySource, type StrikingDistanceOptions, type StrikingDistanceResult, type StrikingDistanceSortMetric, type TypedQuery, type TypedRowQuery, type WindowPreset, type ZeroClickResult, analyzeBrandSegmentation, analyzeBrandSegmentationFromSource, analyzeCannibalization, analyzeClustering, analyzeClusteringFromSource, analyzeConcentration, analyzeDecay, analyzeDecayFromSource, analyzeFromSource, analyzeInBrowser, analyzeKeywordConcentration, analyzeKeywordConcentrationFromSource, analyzeMovers, analyzeMoversFromSource, analyzeOpportunityFromSource, analyzePageConcentration, analyzePageConcentrationFromSource, analyzeSeasonality, analyzeSeasonalityFromSource, analyzeStrikingDistance, analyzeStrikingDistanceFromSource, comparisonOf, createAnalyzerRegistry, createCompositeSource, createEngineQuerySource, createInMemoryQuerySource, createSorter, defaultAnalyzerRegistry, defaultReportRegistry, defineAnalyzer, dryRunReport, formatReport, isSqlQuerySource, mergePriorityActions, normalizePriorityActions, normalizeQuery, num, padTimeseries, periodOf, queryAnalyticsFromSource, queryComparisonFromSource, queryComparisonRows, queryRows, resolveWindow, rewriteForTableSource, runAnalyzerFromSource, runAnalyzerWithEngine, runReport, scorePriorityActions, typedQuery, windowToComparisonPeriod, windowToPeriod };
+export { type ActionPriorityResult, type ActionPrioritySourceState, type ActionPrioritySourceStatus, type ActionSource, type AnalysisParams, type AnalysisPeriod, type AnalysisQuerySource, type AnalysisResult, type AnalysisSourceKind, type AnalysisTool, type Analyzer, AnalyzerCapabilityError, type AnalyzerRegistry, type AnalyzerRegistryInit, type AnalyzerRunner, type AnalyzerVariants, type BaseMetrics, type BrandSegmentationOptions, type BrandSegmentationResult, type BrandSummary, type BrowserAnalyzeOptions, type CannibalizationCompetitor, type CannibalizationEvent, type CannibalizationOptions, type CannibalizationPage, type CannibalizationResult, type CannibalizationSortMetric, type ClusterType, type ClusteringOptions, type ClusteringResult, type ComparisonMode, type ComparisonPeriod, type CompositeSourceOptions, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, DEFAULT_PRIORITY_SOURCES, type DateRow, type DecayInput, type DecayOptions, type DecayResult, type DecaySeriesPoint, type DecaySortMetric, type DefineAnalyzerOptions, type DefineReportOptions, type DefinedAnalyzer, type DefinedReport, type DryRunReportResult, ENGINE_QUERY_CAPABILITIES, type Effort, type EngineQuerySourceOptions, type ExecuteSqlOptions, type FileSet, type FormatReportOptions, IN_MEMORY_DEFAULT_CAPABILITIES, type InMemoryQuerySourceOptions, type KeywordCluster, type KeywordRow, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversSortMetric, type OpportunityResult, type PadTimeseriesOptions, type PageRow, type Plan, type PriorityAction, type QueryPageRow, type QueryRow, REPORTS, ROW_ANALYZERS, type ReduceContext, type ReduceCtx, type Reducer, type ReportAction, type ReportContext, type ReportFinding, type ReportPlanStep, type ReportResult, type ReportSection, type RequiredCapability, type ResolveWindowOptions, type ResolvedWindow, type RowQueriesPlan, type RunReportOptions, SQL_ANALYZERS, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type SortOrder, type SourceCapabilities, type SqlExtraQuery, type SqlPlan, type SqlPlanSpec, type StrikingDistanceInputRow, type StrikingDistanceResult, type TypedQuery, type TypedRowQuery, type WindowPreset, type ZeroClickResult, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeInBrowser, analyzeKeywordConcentration, analyzeMovers, analyzePageConcentration, analyzeSeasonality, comparisonOf, createAnalyzerRegistry, createCompositeSource, createEngineQuerySource, createInMemoryQuerySource, createSorter, defaultAnalyzerRegistry, defaultReportRegistry, defineAnalyzer, dryRunReport, formatReport, mergePriorityActions, normalizePriorityActions, normalizeQuery, num, padTimeseries, periodOf, queryComparisonRows, queryRows, resolveWindow, rewriteForTableSource, runAnalyzerFromSource, runAnalyzerWithEngine, runReport, scorePriorityActions, typedQuery, windowToComparisonPeriod, windowToPeriod };