@gscdump/analysis 0.40.2 → 1.0.0

package/dist/analyzer/index.d.mts

@@ -1,761 +0,0 @@
-import { AnalysisPeriod } from "@gscdump/engine/period";
-import { BuilderState } from "gscdump/query";
-import { Row } from "@gscdump/engine/contracts";
-/**
- * `bayesian-ctr` — Empirical-Bayes CTR shrinkage. SQL-only colocation.
- *
- * Migrated from `engine-duckdb-node/src/analyzers/bayesian-ctr.ts`.
- */
-interface BayesianCtrResult {
-  keyword: string;
-  page: string;
-  clicks: number;
-  impressions: number;
-  observedCtr: number;
-  position: number;
-  bucket: number;
-  priorAlpha: number;
-  priorBeta: number;
-  bucketPriorMean: number;
-  posteriorMean: number;
-  posteriorSd: number;
-  ciLow: number;
-  ciHigh: number;
-  shrinkageDelta: number;
-  expectedClicksDelta: number;
-  significance: number;
-  classification: 'overperforming' | 'underperforming' | 'expected';
-}
-declare const bayesianCtrAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * bipartite-pagerank
- *
- * Personalized PageRank on the (query <-> url) bipartite graph, edge-weighted
- * by impressions. Each power-iteration "step" is two half-steps: queries
- * receive mass from URLs, then URLs receive mass from queries. We express
- * the fixed-N iteration as a chain of CTEs built programmatically (bounded
- * unroll). This sidesteps DuckDB's recursive-CTE restriction on aggregate
- * functions over the recursive reference; the natural formulation needs
- * SUM(prev.rank * weight) GROUP BY node_id, which recursive CTEs reject.
- *
- * "Hub queries" bridge many URLs with roughly-even mass distribution;
- * "hub URLs" anchor many queries the same way. Rank is eigenvector
- * centrality: a node is important if it links to other important nodes.
- */
-interface BipartitePagerankNode {
-  kind: 'query' | 'url';
-  id: string;
-  rank: number;
-  bridging: number;
-  anchoring: number;
-  degree: number;
-  impressions: number;
-}
-type BipartitePagerankResult = BipartitePagerankNode;
-declare const bipartitePagerankAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * 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 {
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-}
-/** Keyword row from query */
-interface QueriesRow extends BaseMetrics {
-  query: string;
-  page?: string;
-}
-/** Page row from query */
-interface PageRow extends BaseMetrics {
-  page: string;
-}
-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 BrandSegmentationRow {
-  query?: string;
-  keyword?: string;
-  variants?: readonly string[];
-  clicks?: number | null;
-  impressions?: number | null;
-}
-interface BrandSummary {
-  brandClicks: number;
-  nonBrandClicks: number;
-  brandShare: number;
-  brandImpressions: number;
-  nonBrandImpressions: number;
-}
-interface BrandSegmentationResult<T extends BrandSegmentationRow = QueriesRow> {
-  brand: T[];
-  nonBrand: T[];
-  summary: BrandSummary;
-}
-interface BrandResultRow {
-  query: string;
-  page?: string;
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-  segment: 'brand' | 'non-brand';
-}
-declare const brandAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-type CannibalizationSortMetric = 'clicks' | 'impressions' | 'positionSpread' | 'pageCount';
-interface CannibalizationOptions {
-  /** Minimum impressions for a query to be considered. Default: 10 */
-  minImpressions?: number;
-  /** Maximum position spread to flag as cannibalization. Default: 10 */
-  maxPositionSpread?: number;
-  /** Minimum number of pages ranking for same query. Default: 2 */
-  minPages?: number;
-  /** Sort metric. Default: clicks */
-  sortBy?: CannibalizationSortMetric;
-  /** Sort order. Default: desc */
-  sortOrder?: SortOrder;
-}
-interface CannibalizationPage {
-  page: string;
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-}
-interface CannibalizationResult {
-  query: string;
-  pages: CannibalizationPage[];
-  totalClicks: number;
-  totalImpressions: number;
-  positionSpread: number;
-}
-interface CannibalizationCompetitor {
-  url: string;
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-  share: number;
-  rank: number;
-}
-interface CannibalizationEvent {
-  keyword: string;
-  totalImpressions: number;
-  totalClicks: number;
-  competitorCount: number;
-  leaderUrl: string;
-  leaderCtr: number;
-  leaderPosition: number;
-  hhi: number;
-  fragmentation: number;
-  stolenClicks: number;
-  severity: number;
-  competitors: CannibalizationCompetitor[];
-}
-declare const cannibalizationAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * `change-point` — per-(query, url) timeseries change-point detection. SQL-only.
- *
- * Migrated from `engine-duckdb-node/src/analyzers/change-point.ts`.
- */
-interface ChangePointSeriesPoint {
-  date: string;
-  value: number;
-}
-interface ChangePointResult {
-  keyword: string;
-  page: string;
-  totalDays: number;
-  totalImpressions: number;
-  changeDate: string;
-  llr: number;
-  leftMean: number;
-  rightMean: number;
-  delta: number;
-  leftStddev: number;
-  rightStddev: number;
-  direction: 'improved' | 'worsened';
-  series: ChangePointSeriesPoint[];
-}
-declare const changePointAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-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: QueriesRow[];
-  totalClicks: number;
-  totalImpressions: number;
-  avgPosition: number;
-  keywordCount: number;
-}
-interface ClusteringResult {
-  clusters: KeywordCluster[];
-  unclustered: QueriesRow[];
-}
-declare const clusteringAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-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 ConcentrationInput {
-  key: string;
-  clicks: 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;
-}
-declare const concentrationAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * `content-velocity` — weekly new-keyword cadence. SQL-only colocation.
- *
- * Migrated from `engine-duckdb-node/src/analyzers/content-velocity.ts`.
- */
-interface ContentVelocityWeek {
-  week: string;
-  newKeywords: number;
-  totalKeywords: number;
-}
-declare const contentVelocityAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * `ctr-anomaly` — rolling CTR envelope per (query, page). SQL-only colocation.
- *
- * Migrated from `engine-duckdb-node/src/analyzers/ctr-anomaly.ts`.
- */
-interface CtrAnomalySeriesPoint {
-  date: string;
-  ctr: number;
-  position: number;
-  impressions: number;
-  rollingCtr: number | null;
-  rollingStddev: number | null;
-  z: number;
-  breach: boolean;
-}
-interface CtrAnomalyResult {
-  keyword: string;
-  page: string;
-  breachDaysDown: number;
-  breachDaysUp: number;
-  clicksLost: number;
-  severity: number;
-  maxZ: number;
-  baselineCtr: number;
-  baselinePosition: number;
-  totalImpressions: number;
-  totalClicks: number;
-  series: CtrAnomalySeriesPoint[];
-}
-declare const ctrAnomalyAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * `ctr-curve` — CTR by position bucket plus over/under-performing outliers.
- * SQL-only colocation.
- *
- * Migrated from `engine-duckdb-node/src/analyzers/ctr-curve.ts`.
- */
-interface CtrCurveBucket {
-  bucket: string;
-  avgCtr: number;
-  medianPosition: number;
-  keywordCount: number;
-  totalClicks: number;
-  totalImpressions: number;
-}
-interface CtrCurveOutlier {
-  query: string;
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-  expectedCtr: number;
-  ctrDiff: number;
-}
-declare const ctrCurveAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * dark-traffic — gap between page-level clicks and sum-of-keyword clicks.
- *
- * Reads three tables: pages (primary), keywords (summary aggregate),
- * page_keywords (per-page attribution). Uses `extraFiles` for the latter two.
- */
-interface DarkTrafficResult {
-  url: string;
-  totalClicks: number;
-  attributedClicks: number;
-  darkClicks: number;
-  darkPercent: number;
-  keywordCount: number;
-}
-declare const darkTrafficAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-type DataDetailResult = Row;
-declare const dataDetailAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-type DataQueryResult = Row;
-declare const dataQueryAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-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 DecayInput {
-  current: PageRow[];
-  previous: PageRow[];
-}
-interface DecaySeriesPoint {
-  week: string;
-  clicks: number;
-  impressions: number;
-}
-interface DecayResult {
-  page: string;
-  currentClicks: number;
-  previousClicks: number;
-  lostClicks: number;
-  declinePercent: number;
-  /** `null` when the page had no ranking data in the current period (not "position 0"). */
-  currentPosition: number | null;
-  previousPosition: number;
-  /** `null` unless both currentPosition and previousPosition exist. */
-  positionDrop: number | null;
-  series?: DecaySeriesPoint[];
-}
-declare const decayAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * device-gap — desktop vs mobile CTR/position delta over time.
- */
-interface DeviceDayMetrics {
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-}
-interface DeviceGapResult {
-  date: string;
-  desktop: DeviceDayMetrics;
-  mobile: DeviceDayMetrics;
-  gaps: {
-    ctrGap: number;
-    positionGap: number;
-  };
-}
-declare const deviceGapAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * intent-atlas
- *
- * Token-cooccurrence clustering. Tokenizes queries via regexp_split_to_array
- * + unnest, drops stop-words and short tokens, weights tokens by impressions,
- * then clusters each query by its top-2 highest-impression tokens (sorted +
- * joined as the cluster key).
- */
-interface IntentAtlasResult {
-  clusterKey: string;
-  keywordCount: number;
-  totalImpressions: number;
-  totalClicks: number;
-  ctr: number;
-  avgPosition: number;
-  keywords: Array<{
-    query: string;
-    impressions: number;
-    clicks: number;
-    position: number;
-  }>;
-}
-declare const intentAtlasAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * keyword-breadth — keyword-count histogram across pages + fragile/authority
- * classification.
- */
-interface KeywordBreadthResult {
-  bucket: string;
-  pageCount: number;
-}
-declare const keywordBreadthAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * long-tail
- *
- * Per-page power-law fit on log(rank) vs log(impressions) via DuckDB's
- * REGR_SLOPE / REGR_INTERCEPT / REGR_R2 regression aggregates.
- */
-interface LongTailResult {
-  page: string;
-  queryCount: number;
-  totalImpressions: number;
-  totalClicks: number;
-  slope: number;
-  intercept: number;
-  r2: number;
-  headImpressions: number;
-  headShare: number;
-  fingerprint: 'flat-tail' | 'balanced' | 'head-heavy';
-  points: Array<{
-    rank: number;
-    impressions: number;
-    clicks: number;
-    query: string;
-  }>;
-}
-declare const longTailAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-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 MoversInput {
-  current: QueriesRow[];
-  previous: QueriesRow[];
-  /** If periods have different lengths, provide normalization factor (previous/current) */
-  normalizationFactor?: number;
-}
-interface MoverData {
-  keyword: string;
-  page: string | null;
-  recentClicks: number;
-  recentImpressions: number;
-  recentPosition: number;
-  baselineClicks: number;
-  baselineImpressions: number;
-  /** `null` when the keyword has no previous-period data (a genuinely new query), not "position 0". */
-  baselinePosition: number | null;
-  clicksChange: number;
-  clicksChangePercent: number;
-  impressionsChangePercent: number;
-  /** `null` unless both recentPosition and baselinePosition exist. */
-  positionChange: number | null;
-}
-interface MoversResult {
-  rising: MoverData[];
-  declining: MoverData[];
-  stable: MoverData[];
-}
-interface MoversSeriesPoint {
-  week: string;
-  clicks: number;
-  impressions: number;
-}
-interface MoversResultRow extends MoverData {
-  direction: 'rising' | 'declining' | 'stable';
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-  prevClicks: number;
-  prevImpressions: number;
-  prevPosition: number | null;
-  series?: MoversSeriesPoint[];
-}
-declare const moversAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-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;
-}
-declare const opportunityAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * position-distribution — daily count of keywords per position bucket.
- * Matches `/api/sites/[siteId]/position-distribution.get.ts`.
- */
-interface PositionDistributionResult {
-  date: string;
-  pos_1_3: number;
-  pos_4_10: number;
-  pos_11_20: number;
-  pos_20_plus: number;
-  total: number;
-}
-declare const positionDistributionAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * position-volatility
- *
- * Per (page, day) compute query-level position STDDEV_POP plus day-over-day
- * shift in weighted avg position via LAG. The resulting "volatility score"
- * (σ + |Δpos|) surfaces pages whose SERP positioning is genuinely noisy,
- * not just pages that rank well. Output is a pages × dates matrix for a
- * calendar-style heatmap.
- */
-interface PositionVolatilityDay {
-  date: string;
-  queryCount: number;
-  dayImpressions: number;
-  avgPosition: number;
-  posStddev: number;
-  bestPosition: number;
-  worstPosition: number;
-  dodShift: number;
-  volatility: number;
-}
-interface PositionVolatilityResult {
-  page: string;
-  avgVolatility: number;
-  peakVolatility: number;
-  totalImpressions: number;
-  days: PositionVolatilityDay[];
-}
-declare const positionVolatilityAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * query-migration
- *
- * Two-period query absorption analysis. For each (page, query) pair lost in
- * the previous period and (page, query) gained in the current period across
- * different* pages, match via either exact string or `levenshtein()` ≤ 2
- * edits. The matched edge represents impressions that *probably* migrated
- * from page-A to page-B as Google reassigned the ranking URL.
- *
- * Output: a sankey-ready edge list grouped by (sourcePage → targetPage),
- * weighted by absorbed impressions, with example query pairs attached.
- */
-interface QueryMigrationExample {
-  sourceQuery: string;
-  targetQuery: string;
-  absorbed: number;
-  matchType: 'exact' | 'fuzzy';
-}
-interface QueryMigrationResult {
-  sourcePage: string;
-  targetPage: string;
-  weight: number;
-  queryCount: number;
-  exactCount: number;
-  fuzzyCount: number;
-  examples: QueryMigrationExample[];
-}
-declare const queryMigrationAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-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;
-}
-declare const seasonalityAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * stl-decompose
- *
- * Classical additive decomposition: observed = trend + seasonal + residual.
- * Trend is a centered 7-day moving average; seasonal is the mean of detrended
- * residuals per-dayofweek per-entity; residual is the leftover. Entities with
- * a large |residual| relative to STDDEV_POP(residual) are flagged anomalous.
- * Not true STL (no iterative LOESS), but faithful where it matters and
- * expressible in pure DuckDB window functions.
- */
-interface StlDecomposeSeriesPoint {
-  date: string;
-  observed: number;
-  trend: number | null;
-  seasonal: number | null;
-  residual: number | null;
-  anomaly: boolean;
-}
-interface StlDecomposeResult {
-  keyword: string;
-  page: string;
-  totalImpressions: number;
-  days: number;
-  seasonalStrength: number;
-  trendStrength: number;
-  residualAnomalies: number;
-  trendSlope: number;
-  series: StlDecomposeSeriesPoint[];
-}
-declare const stlDecomposeAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * 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;
-}
-declare const strikingDistanceAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * survival (Kaplan-Meier)
- *
- * Models "keyword survival in top-10". An episode starts the first day a
- * (query, url) daily avg position drops to ≤10; it ends the first day
- * position rises above 10 (simpler than the 3-day grace rule — a single bad
- * day is rare enough at the daily-aggregate level to still give a clean
- * tenure signal, and it avoids a windowed state machine in SQL). If the run
- * reaches window_end - 2, the episode is censored (still alive).
- *
- * KM cumulative product is computed via EXP(SUM(LN(...)) OVER ...) — DuckDB
- * has no CUMPROD, but running sums of logs with GREATEST(.., 1e-9) give the
- * same result without any host-side math.
- */
-interface SurvivalCurvePoint {
-  tenure: number;
-  survival: number;
-  atRisk: number;
-  events: number;
-}
-interface SurvivalResult {
-  cohort: string;
-  episodeCount: number;
-  censoringRate: number;
-  medianTenure: number;
-  curve: SurvivalCurvePoint[];
-}
-declare const survivalAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-/**
- * trends — weekly trajectory over a rolling window (default 28 weeks)
- */
-type TrendCategory = 'accelerating' | 'growing' | 'steady' | 'declining' | 'cratering';
-interface TrendSeriesPoint {
-  week: string;
-  clicks: number;
-  impressions: number;
-}
-interface TrendsResult {
-  query?: string;
-  page?: string;
-  totalClicks: number;
-  totalImpressions: number;
-  weeksWithData: number;
-  slope: number;
-  growthRatio: number;
-  avgPosition: number;
-  trend: TrendCategory;
-  series: TrendSeriesPoint[];
-}
-declare const trendsAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-interface ZeroClickResult {
-  query: string;
-  page: string;
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-}
-declare const zeroClickAnalyzer: import("@gscdump/engine/analyzer").DefinedAnalyzer;
-declare function queriesQueryState(period: AnalysisPeriod, limit?: number): BuilderState;
-declare function pagesQueryState(period: AnalysisPeriod, limit?: number): BuilderState;
-declare function datesQueryState(period: AnalysisPeriod, limit?: number): BuilderState;
-/**
- * Pagination helpers shared across analyzers. SQL builders compose
- * `paginateClause` into their tail; row reducers use `paginateInMemory`
- * to slice already-materialized results.
- *
- * Sort whitelisting stays per-analyzer because each result shape has its
- * own valid columns. `resolveSort` provides a tiny safe-cast.
- */
-interface PaginateInput {
-  limit?: number;
-  offset?: number;
-}
-declare function clampLimit(limit: number | undefined, fallback?: number): number;
-declare function clampOffset(offset: number | undefined): number;
-/**
- * Emits `LIMIT n` or `LIMIT n OFFSET m` literally (no placeholders) so it
- * can be safely concatenated into the analyzer's SQL tail. Inputs are
- * coerced and clamped — never user-controllable.
- */
-declare function paginateClause(input: PaginateInput): string;
-/**
- * Slice a materialized result array. Use in row reducers and in SQL
- * reducers when SQL didn't push pagination down.
- */
-declare function paginateInMemory<T>(rows: readonly T[], input: PaginateInput): T[];
-/**
- * Resolve `sortBy` against an allow-list. Returns a typed key + direction
- * suitable for ORDER BY interpolation or for indexing into a comparator
- * map. Falls back to the analyzer's default when input is missing or
- * unrecognized.
- */
-declare function resolveSort<K extends string>(input: {
-  sortBy?: string;
-  sortDir?: 'asc' | 'desc';
-}, allowed: readonly K[], defaults: {
-  sortBy: K;
-  sortDir: 'asc' | 'desc';
-}): {
-  sortBy: K;
-  sortDir: 'asc' | 'desc';
-};
-export { type BayesianCtrResult, type BipartitePagerankNode, type BipartitePagerankResult, type BrandResultRow, type BrandSegmentationOptions, type BrandSegmentationResult, type BrandSummary, type CannibalizationCompetitor, type CannibalizationEvent, type CannibalizationOptions, type CannibalizationPage, type CannibalizationResult, type CannibalizationSortMetric, type ChangePointResult, type ChangePointSeriesPoint, type ClusterType, type ClusteringOptions, type ClusteringResult, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, type ContentVelocityWeek, type CtrAnomalyResult, type CtrAnomalySeriesPoint, type CtrCurveBucket, type CtrCurveOutlier, type DarkTrafficResult, type DataDetailResult, type DataQueryResult, type DecayInput, type DecayOptions, type DecayResult, type DecaySeriesPoint, type DecaySortMetric, type DeviceGapResult, type IntentAtlasResult, type KeywordBreadthResult, type KeywordCluster, type LongTailResult, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversResultRow, type MoversSeriesPoint, type MoversSortMetric, type OpportunityResult, type PaginateInput, type PositionDistributionResult, type PositionVolatilityDay, type PositionVolatilityResult, type QueryMigrationExample, type QueryMigrationResult, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type StlDecomposeResult, type StlDecomposeSeriesPoint, type StrikingDistanceInputRow, type StrikingDistanceResult, type SurvivalCurvePoint, type SurvivalResult, type TrendCategory, type TrendSeriesPoint, type TrendsResult, type ZeroClickResult, bayesianCtrAnalyzer, bipartitePagerankAnalyzer, brandAnalyzer, cannibalizationAnalyzer, changePointAnalyzer, clampLimit, clampOffset, clusteringAnalyzer, concentrationAnalyzer, contentVelocityAnalyzer, ctrAnomalyAnalyzer, ctrCurveAnalyzer, darkTrafficAnalyzer, dataDetailAnalyzer, dataQueryAnalyzer, datesQueryState, decayAnalyzer, deviceGapAnalyzer, intentAtlasAnalyzer, keywordBreadthAnalyzer, longTailAnalyzer, moversAnalyzer, opportunityAnalyzer, pagesQueryState, paginateClause, paginateInMemory, positionDistributionAnalyzer, positionVolatilityAnalyzer, queriesQueryState, queryMigrationAnalyzer, resolveSort, seasonalityAnalyzer, stlDecomposeAnalyzer, strikingDistanceAnalyzer, survivalAnalyzer, trendsAnalyzer, zeroClickAnalyzer };