gscdump 0.1.3 → 0.3.0

package/dist/index.d.mts

@@ -1,4 +1,3 @@
-import _dayjs, { Dayjs } from "dayjs";
 import { $Fetch, FetchOptions } from "ofetch";
 import { indexing_v3 } from "@googleapis/indexing/v3";
 import { searchconsole_v1 } from "@googleapis/searchconsole/v1";
@@ -71,500 +70,109 @@ interface SiteAnalytics {
   }[];
 }
 //#endregion
-//#region src/api/search-analytics/types.d.ts
-type DataType = 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
-type DataState = 'final' | 'all';
-type AggregationType = 'byPage' | 'byProperty';
-interface QueryOptions {
-  period?: Period;
-  prevPeriod?: Period;
-  domain?: string;
-  filters?: DimensionFilter[];
-  /** Data type: web, image, video, news, discover, googleNews. Default: web */
-  type?: DataType;
-  /** Data state: final (settled data) or all (includes fresh/unfinalized). Default: all */
-  dataState?: DataState;
-  /**
-   * Aggregation type: byPage (per-URL metrics) or byProperty (domain-level rollup).
-   * Use byProperty for sc-domain: properties to get true totals.
-   * byPage can undercount when same query hits multiple pages.
-   * Default: byPage
-   */
-  aggregationType?: AggregationType;
-  /** Maximum rows to return. Default: 25000 (GSC API limit per request) */
-  rowLimit?: number;
-}
-interface ComparisonResult<T> {
-  current: T[];
-  previous: T[];
-  metadata?: {
-    currentCount: number;
-    previousCount: number;
-    [key: string]: unknown;
-  };
-}
-interface DeviceData extends Omit<DataRow, 'keys'> {
-  dimension: 'device';
-  device: string;
-  keys: null;
-}
-interface CountryData extends Omit<DataRow, 'keys'> {
-  dimension: 'country';
-  countryCodeGsc: string;
-  country: string;
-  countryCode: string;
-  keywords?: number;
-  keys: null;
-}
-interface AnalyticsData extends Omit<DataRow, 'keys'> {
-  keywords: DataRow[];
-}
-interface PageData extends Omit<DataRow, 'keys'> {
-  dimension: 'page';
-  page: string;
-  keyword?: string;
-  keywordPosition?: number;
-  prevClicks?: number;
-  clicksPercent?: number;
-  prevImpressions?: number;
-  impressionsPercent?: number;
-  lost?: boolean;
-  keys: null;
-}
-interface KeywordData extends Omit<DataRow, 'keys'> {
-  dimension: 'query';
-  keyword: string;
-  page?: string | null;
-  positionPercent?: number;
-  prevPosition?: number;
-  ctrPercent?: number;
-  prevCtr?: number;
-  lost?: boolean;
-  prevClicks?: number;
-  prevImpressions?: number;
-  keys: null;
-}
-interface DateData extends Omit<DataRow, 'keys'> {
-  dimension: 'date';
-  date: string;
-  keys: null;
-}
-interface SearchAppearanceData extends Omit<DataRow, 'keys'> {
-  dimension: 'searchAppearance';
-  searchAppearance: string;
-  keys: null;
-}
-/**
- * Discriminated union of all query result row types.
- * Use the `dimension` field to narrow to specific types.
- */
-type QueryResultRow = DateData | DeviceData | CountryData | PageData | KeywordData | SearchAppearanceData;
-interface DateRow extends Omit<DataRow, 'keys'> {
-  date: string;
-  keys: null;
-}
-interface KeywordRow extends Omit<DataRow, 'keys'> {
-  keyword: string;
-  keys: null;
-}
-interface PageRow extends Omit<DataRow, 'keys'> {
-  page: string;
-  keys: null;
-}
-interface FetchPageResult {
-  dates: DateRow[];
-  keywords: KeywordRow[];
-}
-interface FetchKeywordResult {
-  dates: DateRow[];
-  pages: PageRow[];
-}
+//#region src/query/utils/countries.d.ts
+declare const _default: {
+  name: string;
+  'alpha-2': string;
+  'alpha-3': string;
+  'country-code': string;
+}[];
 //#endregion
-//#region src/analysis/brand.d.ts
-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: KeywordData[];
-  nonBrand: KeywordData[];
-  summary: BrandSummary;
-}
-/**
- * Segments keywords into brand and non-brand based on provided brand terms.
- * Simple string matching - keyword contains any brand term (case-insensitive).
- */
-declare function analyzeBrandSegmentation(keywords: KeywordData[], options: BrandSegmentationOptions): BrandSegmentationResult;
+//#region src/query/constants.d.ts
+declare const Devices: {
+  readonly MOBILE: "MOBILE";
+  readonly DESKTOP: "DESKTOP";
+  readonly TABLET: "TABLET";
+};
+type Device = typeof Devices[keyof typeof Devices];
+declare const SearchTypes: {
+  readonly WEB: "web";
+  readonly IMAGE: "image";
+  readonly VIDEO: "video";
+  readonly NEWS: "news";
+};
+type SearchType = typeof SearchTypes[keyof typeof SearchTypes];
+declare const Countries: { [K in (typeof _default)[number]["alpha-3"]]: Lowercase<K> };
+type Country = typeof Countries[keyof typeof Countries];
 //#endregion
-//#region src/analysis/types.d.ts
-/**
- * Shared types for pure analysis functions.
- * These types describe the inputs and outputs of analysis functions
- * that operate on data, independent of how it was fetched.
- */
-type SortOrder = 'asc' | 'desc';
-/** Base search metrics present on all data rows */
-interface BaseMetrics {
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-}
-/** Row with both query and page dimensions */
-interface QueryPageRow extends BaseMetrics {
+//#region src/query/types.d.ts
+interface DimensionValueMap {
   query: string;
+  queryCanonical: string;
   page: string;
-}
-/** Date-keyed metrics for time series analysis */
-interface DateMetrics extends BaseMetrics {
+  country: Country;
+  device: Device;
+  searchAppearance: string;
   date: string;
 }
-/** Coerce nullable number to number, defaulting to 0 */
-declare function num(value: number | null | undefined): number;
-/** Create a generic sorter for any metric type */
-declare function createSorter<T, M extends string>(getValue: (item: T, metric: M) => number, defaultMetric: M, defaultOrder?: SortOrder): (items: T[], sortBy?: M, sortOrder?: SortOrder) => T[];
-//#endregion
-//#region src/analysis/cannibalization.d.ts
-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;
-}
-/**
- * Detects keyword cannibalization - queries ranking for multiple pages.
- * Returns queries where multiple pages compete for the same search term.
- *
- * @param rows Query+page data rows
- * @param options Filtering and sorting options
- */
-declare function analyzeCannibalization(rows: QueryPageRow[], options?: CannibalizationOptions): CannibalizationResult[];
-//#endregion
-//#region src/analysis/clustering.d.ts
-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: KeywordData[];
-  totalClicks: number;
-  totalImpressions: number;
-  avgPosition: number;
-  keywordCount: number;
-}
-interface ClusteringResult {
-  clusters: KeywordCluster[];
-  unclustered: KeywordData[];
-}
-/**
- * Clusters keywords by intent prefix or common word prefix.
- * Simple regex/prefix approach - no external NLP dependencies.
- *
- * @param keywords Array of keyword data
- * @param options Clustering options
- */
-declare function analyzeClustering(keywords: KeywordData[], options?: ClusteringOptions): ClusteringResult;
-//#endregion
-//#region src/analysis/concentration.d.ts
-/**
- * Traffic concentration analysis - measures distribution across pages/keywords.
- * Pure function operating on page or keyword data.
- */
-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;
-}
-/** Item with a key and clicks for concentration analysis */
-interface ConcentrationInput {
-  key: string;
-  clicks: number;
-}
-/**
- * Analyzes traffic concentration across items (pages or keywords).
- * Returns Gini coefficient, HHI, and top-N concentration metrics.
- *
- * @param items Array of items with key and clicks
- * @param options Configuration options
- */
-declare function analyzeConcentration(items: ConcentrationInput[], options?: ConcentrationOptions): ConcentrationResult;
-/** Item with page and optional/nullable clicks */
-interface PageLike {
-  page: string;
-  clicks?: number | null;
-}
-/** Item with keyword and optional/nullable clicks */
-interface KeywordLike {
-  keyword: string;
-  clicks?: number | null;
-}
-/**
- * Convenience wrapper for page concentration analysis.
- */
-declare function analyzePageConcentration(pages: PageLike[], options?: ConcentrationOptions): ConcentrationResult;
-/**
- * Convenience wrapper for keyword concentration analysis.
- */
-declare function analyzeKeywordConcentration(keywords: KeywordLike[], options?: ConcentrationOptions): ConcentrationResult;
-//#endregion
-//#region src/analysis/decay.d.ts
-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: PageData[];
-  previous: PageData[];
-}
-interface DecayResult {
-  page: string;
-  currentClicks: number;
-  previousClicks: number;
-  lostClicks: number;
-  declinePercent: number;
-  currentPosition: number;
-  previousPosition: number;
-  positionDrop: number;
-}
-/**
- * Identifies "decaying" content - pages that have lost significant traffic.
- * Useful for finding old content that needs updating.
- *
- * @param input Current and previous period page data
- * @param options Filtering and sorting options
- */
-declare function analyzeDecay(input: DecayInput, options?: DecayOptions): DecayResult[];
-//#endregion
-//#region src/analysis/movers.d.ts
-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: KeywordData[];
-  previous: KeywordData[];
-  /** 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;
-  baselinePosition: number;
-  clicksChange: number;
-  clicksChangePercent: number;
-  impressionsChangePercent: number;
-  positionChange: number;
-}
-interface MoversResult {
-  rising: MoverData[];
-  declining: MoverData[];
-  stable: MoverData[];
+type Dimension = keyof DimensionValueMap;
+interface QueryParamValueMap {
+  searchType: SearchType;
 }
-/**
- * Identifies movers and shakers - keywords with significant recent changes.
- * Compares recent period against baseline period.
- *
- * @param input Current and previous keyword data
- * @param options Filtering and sorting options
- */
-declare function analyzeMovers(input: MoversInput, options?: MoversOptions): MoversResult;
-//#endregion
-//#region src/analysis/opportunity.d.ts
-type OpportunitySortMetric = 'opportunityScore' | 'potentialClicks' | 'impressions' | 'position';
-interface OpportunityWeights {
-  position?: number;
-  impressions?: number;
-  ctrGap?: number;
+type QueryParamName = keyof QueryParamValueMap;
+declare const ColumnBrand: unique symbol;
+interface Column<D extends Dimension> {
+  readonly [ColumnBrand]: D;
+  readonly dimension: D;
 }
-interface OpportunityOptions {
-  /** Minimum impressions to consider. Default: 100 */
-  minImpressions?: number;
-  /** Custom weights for score factors. Default: all 1 */
-  weights?: OpportunityWeights;
-  /** Sort metric. Default: opportunityScore */
-  sortBy?: OpportunitySortMetric;
+type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
+type DateOperator = 'gte' | 'gt' | 'lte' | 'lt' | 'between';
+type MetricOperator = 'metricGte' | 'metricGt' | 'metricLte' | 'metricLt' | 'metricBetween';
+type SpecialOperator = 'topLevel';
+interface InternalFilter {
+  dimension: Dimension | QueryParamName | Metric;
+  operator: FilterOperator | DateOperator | MetricOperator | SpecialOperator;
+  expression: string;
+  expression2?: string;
 }
-interface OpportunityFactors {
-  positionScore: number;
-  impressionScore: number;
-  ctrGapScore: number;
+declare const FilterBrand: unique symbol;
+interface Filter<C = object> {
+  readonly [FilterBrand]: true;
+  readonly _constraints: C;
+  readonly _filters: InternalFilter[];
+  readonly _nestedGroups?: Filter<any>[];
+  readonly _groupType?: 'and' | 'or';
 }
-interface OpportunityResult {
-  keyword: string;
-  page: string | null;
+type GSCRow<D extends Dimension[], C> = { [K in D[number]]: K extends keyof C ? C[K] : DimensionValueMap[K] } & {
   clicks: number;
   impressions: number;
   ctr: number;
   position: number;
-  opportunityScore: number;
-  potentialClicks: number;
-  factors: OpportunityFactors;
-}
-/**
- * Scores keywords by optimization opportunity.
- * Composite score combining position, impressions, and CTR gap factors.
- */
-declare function analyzeOpportunity(keywords: KeywordData[], options?: OpportunityOptions): OpportunityResult[];
-//#endregion
-//#region src/analysis/seasonality.d.ts
-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;
-}
-/**
- * Detects seasonality patterns by analyzing monthly traffic variation.
- * Identifies peaks (>1.5x average) and troughs (<0.5x average).
- *
- * @param dates Array of date metrics (each row is one day)
- * @param options Analysis options
- */
-declare function analyzeSeasonality(dates: DateMetrics[], options?: SeasonalityOptions): SeasonalityResult;
-//#endregion
-//#region src/analysis/striking-distance.d.ts
-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 Metric = 'clicks' | 'impressions' | 'ctr' | 'position';
+declare const MetricColumnBrand: unique symbol;
+interface MetricColumn<M extends Metric> {
+  readonly [MetricColumnBrand]: M;
+  readonly metric: M;
 }
-interface StrikingDistanceResult {
-  keyword: string;
-  page: string | null;
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-  /** Estimated clicks if position improved to top 3 */
-  potentialClicks: number;
+interface BuilderState {
+  dimensions: Dimension[];
+  metrics?: Metric[];
+  filter?: Filter<any>;
+  orderBy?: {
+    column: Metric | 'date';
+    dir: 'asc' | 'desc';
+  };
+  rowLimit?: number;
+  startRow?: number;
 }
-/**
- * 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: KeywordData[], options?: StrikingDistanceOptions): StrikingDistanceResult[];
 //#endregion
-//#region src/analysis/zero-click.d.ts
-interface ZeroClickOptions {
-  /** Minimum impressions. Default: 1000 */
-  minImpressions?: number;
-  /** Maximum CTR to be considered "Zero Click". Default: 0.03 (3%) */
-  maxCtr?: number;
-  /** Only consider queries in top X positions. Default: 10 */
-  maxPosition?: number;
-}
-interface ZeroClickResult {
-  query: string;
-  page: string;
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
+//#region src/query/builder.d.ts
+type SelectableColumn = Column<Dimension> | MetricColumn<Metric>;
+type OrderableColumn = MetricColumn<Metric> | Column<'date'>;
+type ExtractDimensions<T extends SelectableColumn[]> = { [K in keyof T]: T[K] extends Column<infer D> ? D : never }[number] extends infer U ? Exclude<U, never>[] : never;
+interface GSCQueryBuilder<D extends Dimension[] = [], C = object> {
+  select: {
+    <T extends Dimension[]>(...dims: T): GSCQueryBuilder<T, C>;
+    <T extends SelectableColumn[]>(...cols: T): GSCQueryBuilder<ExtractDimensions<T> & Dimension[], C>;
+  };
+  where: <F extends Filter<any>>(filter: F) => GSCQueryBuilder<D, C & F['_constraints']>;
+  orderBy: (col: OrderableColumn, dir: 'asc' | 'desc') => GSCQueryBuilder<D, C>;
+  limit: (n: number) => GSCQueryBuilder<D, C>;
+  offset: (n: number) => GSCQueryBuilder<D, C>;
+  toBody: () => SearchAnalyticsQuery;
+  getState: () => BuilderState;
 }
-/**
- * Identifies potential "Zero-Click" queries.
- * These are high-volume queries where you rank well but get few clicks,
- * often due to SERP features (Answer Boxes, Knowledge Panels, AI Overviews).
- *
- * @param rows Query+page data rows
- * @param options Filtering options
- */
-declare function analyzeZeroClick(rows: QueryPageRow[], options?: ZeroClickOptions): ZeroClickResult[];
 //#endregion
 //#region src/core/client.d.ts
 /**
@@ -592,29 +200,26 @@ type Auth = string | {
 } | AuthClient | AuthOptions;
 declare function createFetch(auth: Auth, options?: FetchOptions): $Fetch;
 interface GoogleSearchConsoleClient {
-  sites: {
-    list: () => Promise<{
-      siteEntry?: ApiSite[];
-    }>;
-  };
+  /** Query search analytics with builder, returns async generator yielding typed row batches */
+  query: <D extends Dimension[], C>(siteUrl: string, builder: GSCQueryBuilder<D, C>) => AsyncGenerator<GSCRow<D, C>[]>;
+  /** List all sites */
+  sites: () => Promise<ApiSite[]>;
+  /** Inspect a URL */
+  inspect: (siteUrl: string, url: string) => Promise<InspectUrlIndexResponse>;
+  /** Sitemap operations */
   sitemaps: {
-    list: (siteUrl: string) => Promise<{
-      sitemap?: ApiSitemap[];
-    }>;
+    list: (siteUrl: string) => Promise<ApiSitemap[]>;
     get: (siteUrl: string, feedpath: string) => Promise<ApiSitemap>;
     submit: (siteUrl: string, feedpath: string) => Promise<void>;
     delete: (siteUrl: string, feedpath: string) => Promise<void>;
   };
-  searchAnalytics: {
-    query: (siteUrl: string, body: SearchAnalyticsQuery) => Promise<SearchAnalyticsResponse>;
-  };
-  urlInspection: {
-    inspect: (siteUrl: string, inspectionUrl: string) => Promise<InspectUrlIndexResponse>;
-  };
+  /** Indexing API operations */
   indexing: {
     publish: (url: string, type: 'URL_UPDATED' | 'URL_DELETED') => Promise<PublishUrlNotificationResponse>;
     getMetadata: (url: string) => Promise<UrlNotificationMetadata>;
   };
+  /** @internal */
+  _rawQuery: (siteUrl: string, body: SearchAnalyticsQuery) => Promise<SearchAnalyticsResponse>;
 }
 interface GoogleSearchConsoleClientOptions {
   fetchOptions?: FetchOptions;
@@ -682,287 +287,23 @@ declare function batchInspectUrls(client: GoogleSearchConsoleClient, siteUrl: st
   onProgress?: (result: InspectUrlResult, index: number, total: number) => void;
 }): Promise<InspectUrlResult[]>;
 //#endregion
-//#region src/api/search-analytics/analytics.d.ts
-/**
- * Fetches overall site analytics summary with period comparison and keyword data.
- */
-declare function fetchAnalyticsWithComparison(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<ComparisonResult<AnalyticsData>>;
-//#endregion
-//#region src/api/search-analytics/breakdowns.d.ts
-/**
- * Fetches device breakdown (desktop, mobile, tablet) with period comparison.
- */
-declare function fetchDevicesWithComparison(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<ComparisonResult<DeviceData>>;
-/**
- * Fetches device breakdown (desktop, mobile, tablet).
- */
-declare function fetchDevices(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<DeviceData[]>;
-/**
- * Fetches top countries by traffic with period comparison and keyword counts per country.
- */
-declare function fetchCountriesWithComparison(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<ComparisonResult<CountryData>>;
-/**
- * Fetches top countries by traffic.
- */
-declare function fetchCountries(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<CountryData[]>;
-/**
- * Fetches search appearance breakdown (AMP, rich results, etc.) with period comparison.
- */
-declare function fetchSearchAppearanceWithComparison(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<ComparisonResult<SearchAppearanceData>>;
-/**
- * Fetches search appearance breakdown (AMP, rich results, etc.).
- */
-declare function fetchSearchAppearance(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<SearchAppearanceData[]>;
-//#endregion
-//#region src/api/search-analytics/dates.d.ts
-interface DatesComparisonResult {
-  current: DateData[];
-  previous: DateData[];
-  metadata: {
-    currentCount: number;
-    previousCount: number;
-    totals: {
-      current: {
-        clicks: number;
-        impressions: number;
-        ctr: number;
-        position: number;
-      };
-      previous: {
-        clicks: number;
-        impressions: number;
-        ctr: number;
-        position: number;
-      };
-      clicksPercent: number;
-      impressionsPercent: number;
-      ctrPercent: number;
-      positionPercent: number;
-    };
-  };
-}
-/**
- * Fetches daily search analytics data with period-over-period comparison.
- */
-declare function fetchDatesWithComparison(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<DatesComparisonResult>;
-interface YoYComparisonOptions {
-  /** Current period to compare. If not provided, uses last 28 days */
-  period?: Period;
-}
-interface YoYMetrics {
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-}
-interface YoYComparisonResult {
-  current: YoYMetrics;
-  previous: YoYMetrics;
-  change: {
-    clicks: number;
-    clicksPercent: number;
-    impressions: number;
-    impressionsPercent: number;
-    ctr: number;
-    ctrPercent: number;
-    position: number;
-    positionPercent: number;
-  };
-  periodDays: number;
-  withinLimit: boolean;
-}
-/**
- * Fetches year-over-year comparison for site metrics.
- * GSC has ~16 months history, so works for periods up to ~4 months.
- */
-declare function fetchYoYComparison(client: GoogleSearchConsoleClient, siteUrl: string, options?: YoYComparisonOptions): Promise<YoYComparisonResult>;
-/**
- * Fetches daily search analytics data for a site.
- */
-declare function fetchDates(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<DateData[]>;
-//#endregion
-//#region src/api/search-analytics/keywords.d.ts
-/**
- * Fetches keyword/query performance data with period comparison and associated pages.
- */
-declare function fetchKeywordsWithComparison(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<ComparisonResult<KeywordData>>;
-/**
- * Fetches all keywords with their performance data using recursive pagination.
- */
-declare function fetchKeywords(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<KeywordData[]>;
-interface FetchKeywordOptions extends QueryOptions {
-  /** Maximum pages to return. Default: 5 */
-  rowLimit?: number;
-}
-/**
- * Fetches detailed data for a specific keyword including daily trends and top pages.
- */
-declare function fetchKeyword(client: GoogleSearchConsoleClient, siteUrl: string, keyword: string, options?: FetchKeywordOptions): Promise<FetchKeywordResult>;
-//#endregion
-//#region src/api/search-analytics/pages.d.ts
-interface Page {
-  page: string;
-}
-/**
- * Fetches all pages with their performance data using recursive pagination.
- */
-declare function fetchPages(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<Page[]>;
-/**
- * Fetches page performance data with period comparison, including top keyword per page.
- */
-declare function fetchPagesWithComparison(client: GoogleSearchConsoleClient, siteUrl: string, options?: QueryOptions): Promise<ComparisonResult<PageData>>;
-interface FetchPageOptions extends QueryOptions {
-  /** Maximum keywords to return. Default: 5 */
-  rowLimit?: number;
-}
-/**
- * Fetches detailed data for a specific page including daily trends and top keywords.
- */
-declare function fetchPage(client: GoogleSearchConsoleClient, siteUrl: string, url: string, options?: FetchPageOptions): Promise<FetchPageResult>;
-//#endregion
-//#region src/api/search-analytics/query.d.ts
-/**
- * Recursively queries GSC search analytics, automatically handling pagination for large datasets.
- */
-declare function queryRecursive(client: GoogleSearchConsoleClient, siteUrl: string, query: SearchAnalyticsQuery, options?: {
-  onProgress?: (rows: number) => void;
-}): Promise<{
-  rows: DataRow[];
-  pages: number;
-}>;
-/**
- * Creates a GSC search analytics query request body with standard defaults.
- */
-declare function createQueryBody(options?: QueryOptions): SearchAnalyticsQuery;
-/**
- * Helper to add search appearance dimension filter.
- * Use with spread: createQueryBody({ ...withSearchAppearance('AMP'), period })
- */
-declare function withSearchAppearance(appearance: string): Pick<QueryOptions, 'filters'>;
-/**
- * Helper to set data type (web, image, video, news, discover, googleNews).
- * Use with spread: createQueryBody({ ...withDataType('image'), period })
- */
-declare function withDataType(type: DataType): Pick<QueryOptions, 'type'>;
-/**
- * Helper to include fresh/unfinalized data (last 3 days).
- * Use with spread: createQueryBody({ ...withFreshData(), period })
- */
-declare function withFreshData(): Pick<QueryOptions, 'dataState'>;
-/**
- * Helper to use only finalized data (excludes last 3 days).
- * Use with spread: createQueryBody({ ...withFinalData(), period })
- */
-declare function withFinalData(): Pick<QueryOptions, 'dataState'>;
-/**
- * Helper to use byProperty aggregation (domain-level rollup).
- * Use for sc-domain: properties to get true totals.
- * Use with spread: createQueryBody({ ...withPropertyAggregation(), period })
- */
-declare function withPropertyAggregation(): Pick<QueryOptions, 'aggregationType'>;
-//#endregion
-//#region src/api/search-analytics/stream.d.ts
-/**
- * Supported GSC dimensions for streaming queries.
- * Maps to GSC API dimension names.
- */
-type DimensionKey = 'query' | 'page' | 'date' | 'device' | 'country';
-/**
- * Maps each dimension to its output field name.
- * Note: 'query' maps to 'keyword' to match existing API conventions.
- */
-interface DimensionFields {
-  query: {
-    keyword: string;
-  };
-  page: {
-    page: string;
-  };
-  date: {
-    date: string;
-  };
-  device: {
-    device: string;
-  };
-  country: {
-    country: string;
-  };
-}
-/**
- * Recursively extracts and merges fields for each dimension in a tuple.
- * Used for type inference from dimensions array.
- */
-type ExtractFields<D extends readonly DimensionKey[]> = D extends readonly [infer First extends DimensionKey, ...infer Rest extends DimensionKey[]] ? DimensionFields[First] & ExtractFields<Rest> : object;
-/**
- * Output row type for streaming queries.
- * Combines GSC metrics (clicks, impressions, ctr, position) with
- * typed dimension fields based on the dimensions array.
- *
- * @example
- * // For dimensions: ['query', 'page']
- * // StreamRow = { keyword: string, page: string, clicks?: number, impressions?: number, ctr?: number, position?: number }
- */
-type StreamRow<D extends readonly DimensionKey[]> = Omit<DataRow, 'keys'> & ExtractFields<D>;
-/**
- * Async generator for memory-efficient pagination of GSC search analytics.
- * Yields batches of typed rows as they're fetched, avoiding accumulation in memory.
- *
- * **Design:** Single generic function with type inference replaces separate
- * `fetchPagesStream`, `fetchKeywordsStream` wrappers. Output type is inferred
- * from the dimensions tuple:
- * - `['query']` → `{ keyword: string, clicks, impressions, ctr, position }`
- * - `['page']` → `{ page: string, clicks, impressions, ctr, position }`
- * - `['query', 'page']` → `{ keyword: string, page: string, ... }`
- *
- * Each yield contains up to 25,000 rows (one API page). Use `collectStream()`
- * to gather all batches if full array is needed.
- *
- * @param client - GSC client instance
- * @param siteUrl - Site URL (e.g., 'https://example.com/' or 'sc-domain:example.com')
- * @param query - Query with dimensions array (requires `as const` for type inference)
- *
- * @example
- * ```ts
- * // Stream keyword+page combinations
- * for await (const batch of queryRecursiveStream(client, url, {
- *   dimensions: ['query', 'page'] as const,
- *   startDate: '2024-01-01',
- *   endDate: '2024-01-31',
- * })) {
- *   // batch: { keyword: string, page: string, clicks, impressions, ctr, position }[]
- *   await db.insert(batch)
- * }
- *
- * // Or collect all at once
- * const allRows = await collectStream(queryRecursiveStream(client, url, {
- *   dimensions: ['page'] as const,
- *   startDate: '2024-01-01',
- *   endDate: '2024-01-31',
- * }))
- * ```
- *
- * @remarks
- * - Requires `as const` on dimensions array for proper type inference
- * - Use for large datasets (>25k rows) where memory is a concern
- * - Non-paginating queries (devices, countries) don't benefit from streaming
- */
-declare function queryRecursiveStream<const D extends readonly DimensionKey[]>(client: GoogleSearchConsoleClient, siteUrl: string, query: Omit<SearchAnalyticsQuery, 'dimensions'> & {
-  dimensions: D;
-}): AsyncGenerator<StreamRow<D>[], void, undefined>;
-/** Collect all batches into single array (for testing / simple cases) */
-declare function collectStream<T>(gen: AsyncGenerator<T[], void, undefined>): Promise<T[]>;
-//#endregion
 //#region src/api/sites.d.ts
 /**
  * Fetches all sites the authenticated user has access to in Google Search Console.
  */
 declare function fetchSites(client: GoogleSearchConsoleClient): Promise<ApiSite[]>;
 /**
- * Fetches sitemaps for a site.
+ * Fetches all verified sites with their sitemaps from Google Search Console.
+ */
+declare function fetchSitesWithSitemaps(client: GoogleSearchConsoleClient): Promise<(Site & {
+  sitemaps: RequiredNonNullable<ApiSitemap>[];
+})[]>;
+/**
+ * Fetches all sitemaps for a site.
  */
 declare function fetchSitemaps(client: GoogleSearchConsoleClient, siteUrl: string): Promise<ApiSitemap[]>;
 /**
- * Gets details for a specific sitemap.
+ * Fetches a specific sitemap.
  */
 declare function fetchSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<ApiSitemap>;
 /**
@@ -973,12 +314,29 @@ declare function submitSitemap(client: GoogleSearchConsoleClient, siteUrl: strin
  * Deletes a sitemap from Google Search Console.
  */
 declare function deleteSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<void>;
+//#endregion
+//#region src/core/api-client.d.ts
+interface GscdumpApiOptions {
+  /** API key (gsd_user_xxx or gsd_prod_xxx) */
+  apiKey: string;
+  /** Base URL (defaults to https://gscdump.com) */
+  baseUrl?: string;
+}
 /**
- * Fetches all verified sites with their sitemaps from Google Search Console.
+ * Create a client that queries GSC data through gscdump.com API
+ * instead of directly to Google. Useful when you don't have OAuth credentials.
+ *
+ * @example
+ * ```ts
+ * const client = gscdumpApi({ apiKey: 'gsd_user_xxx' })
+ *
+ * // Same query builder usage as direct client
+ * for await (const rows of client.query(siteId, gsc.select('page', 'query').where(...))) {
+ *   console.log(rows)
+ * }
+ * ```
  */
-declare function fetchSitesWithSitemaps(client: GoogleSearchConsoleClient): Promise<(Site & {
-  sitemaps: RequiredNonNullable<ApiSitemap>[];
-})[]>;
+declare function gscdumpApi(options: GscdumpApiOptions): GoogleSearchConsoleClient;
 //#endregion
 //#region src/core/errors.d.ts
 /**
@@ -1036,144 +394,4 @@ declare function analyzeError(error: unknown): ErrorInfo;
  */
 declare function formatErrorForCli(error: unknown): string;
 //#endregion
-//#region src/utils/countries.d.ts
-declare const _default: {
-  name: string;
-  'alpha-2': string;
-  'alpha-3': string;
-  'country-code': string;
-}[];
-//#endregion
-//#region src/query/constants.d.ts
-declare const Device: {
-  readonly MOBILE: "MOBILE";
-  readonly DESKTOP: "DESKTOP";
-  readonly TABLET: "TABLET";
-};
-type Device = typeof Device[keyof typeof Device];
-declare const Country: { [K in (typeof _default)[number]["alpha-3"]]: Lowercase<K> };
-type Country = typeof Country[keyof typeof Country];
-//#endregion
-//#region src/query/types.d.ts
-interface DimensionValueMap {
-  query: string;
-  page: string;
-  country: Country;
-  device: Device;
-  searchAppearance: string;
-  date: string;
-}
-type Dimension = keyof DimensionValueMap;
-declare const ColumnBrand: unique symbol;
-interface Column<D extends Dimension> {
-  readonly [ColumnBrand]: D;
-  readonly dimension: D;
-}
-type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
-type DateOperator = 'gte' | 'gt' | 'lte' | 'lt' | 'between';
-interface InternalFilter {
-  dimension: Dimension;
-  operator: FilterOperator | DateOperator;
-  expression: string;
-  expression2?: string;
-}
-declare const FilterBrand: unique symbol;
-interface Filter<C = object> {
-  readonly [FilterBrand]: true;
-  readonly _constraints: C;
-  readonly _filters: InternalFilter[];
-  readonly _groupType?: 'and' | 'or';
-}
-type MergeConstraints<F extends Filter<any>[]> = UnionToIntersection<F[number]['_constraints']>;
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
-interface GSCResult<D extends Dimension[], C> {
-  rows: Array<GSCRow<D, C>>;
-}
-type GSCRow<D extends Dimension[], C> = { [K in D[number]]: K extends keyof C ? C[K] : DimensionValueMap[K] } & {
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-};
-interface BuilderState {
-  dimensions: Dimension[];
-  filters: Filter<any>[];
-  siteUrl?: string;
-  rowLimit?: number;
-  startRow?: number;
-}
-//#endregion
-//#region src/query/builder.d.ts
-interface GSCQueryBuilder<D extends Dimension[] = [], C = object> {
-  select: <T extends Dimension[]>(...dims: T) => GSCQueryBuilder<T, C>;
-  where: <F extends Filter<any>>(filter: F) => GSCQueryBuilder<D, C & F['_constraints']>;
-  siteUrl: (url: string) => GSCQueryBuilder<D, C>;
-  limit: (n: number) => GSCQueryBuilder<D, C>;
-  offset: (n: number) => GSCQueryBuilder<D, C>;
-  execute: (client: GoogleSearchConsoleClient) => Promise<GSCResult<D, C>>;
-  toBody: () => SearchAnalyticsQuery;
-  /** Expose internal state for analysis functions to merge with */
-  getState: () => BuilderState;
-}
-declare const gsc: GSCQueryBuilder<[], object>;
-//#endregion
-//#region src/query/columns.d.ts
-declare const page: Column<"page">;
-declare const query: Column<"query">;
-declare const device: Column<"device">;
-declare const country: Column<"country">;
-declare const searchAppearance: Column<"searchAppearance">;
-declare const date: Column<"date">;
-//#endregion
-//#region src/query/operators.d.ts
-declare function eq<D extends Dimension, V extends DimensionValueMap[D]>(column: Column<D>, value: V): Filter<Record<D, V>>;
-declare function ne<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
-declare function inArray<D extends Dimension, V extends DimensionValueMap[D]>(column: Column<D>, values: readonly V[]): Filter<Record<D, V>>;
-declare function contains<D extends Dimension>(column: Column<D>, pattern: string): Filter<object>;
-declare function like<D extends Dimension>(column: Column<D>, pattern: string): Filter<object>;
-declare function regex<D extends Dimension>(column: Column<D>, pattern: RegExp | string): Filter<object>;
-declare function notRegex<D extends Dimension>(column: Column<D>, pattern: RegExp | string): Filter<object>;
-declare function and<F extends Filter<any>[]>(...filters: F): Filter<MergeConstraints<F>>;
-declare function or<F extends Filter<any>[]>(...filters: F): Filter<object>;
-declare function not<F extends Filter<any>>(filter: F): Filter<object>;
-declare function gte<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
-declare function gt<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
-declare function lte<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
-declare function lt<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
-declare function between<D extends Dimension>(column: Column<D>, start: DimensionValueMap[D], end: DimensionValueMap[D]): Filter<object>;
-//#endregion
-//#region src/query/resolver.d.ts
-/**
- * Extract date range from filters. Used by analysis functions to get the period.
- */
-declare function extractDateRange(filters: Filter<any>[]): {
-  startDate?: string;
-  endDate?: string;
-};
-//#endregion
-//#region src/query/index.d.ts
-declare function today(): string;
-declare function daysAgo(n: number): string;
-//#endregion
-//#region src/utils/dayjs.d.ts
-declare function dayjs(date?: _dayjs.ConfigType): Dayjs;
-declare function currentPstDate(): string;
-declare function dayjsPst(): Dayjs;
-//#endregion
-//#region src/utils/format.d.ts
-/**
- * Formats a date for GSC API queries (YYYY-MM-DD format).
- * @param d - Date object, date string, or null/undefined
- * @returns Formatted date string or null/undefined if input is falsy
- */
-declare function formatDateGsc(d?: Date | string | null): string | null | undefined;
-/**
- * Calculates the percentage difference between two values.
- * Returns 0 if either value is null, undefined, or 0 (no meaningful comparison).
- * @param a - Current value
- * @param b - Previous/comparison value
- * @returns Percentage difference (positive = increase, negative = decrease), or 0 if either value is falsy
- */
-declare function percentDifference(a?: number | null, b?: number | null): number;
-//#endregion
-export { AggregationType, AnalyticsData, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, BaseMetrics, BrandSegmentationOptions, BrandSegmentationResult, BrandSummary, type BuilderState, CannibalizationOptions, CannibalizationPage, CannibalizationResult, CannibalizationSortMetric, ClusterType, ClusteringOptions, ClusteringResult, type Column, ComparisonResult, ConcentrationInput, ConcentrationItem, ConcentrationOptions, ConcentrationResult, ConcentrationRiskLevel, Country, type Country as CountryType, CountryData, DataRow, DataState, DataType, DateData, DateMetrics, DateRow, DatesComparisonResult, DecayInput, DecayOptions, DecayResult, DecaySortMetric, Device, type Device as DeviceType, DeviceData, type Dimension, DimensionFilter, DimensionFilterGroup, DimensionKey, type DimensionValueMap, ErrorInfo, FetchKeywordOptions, FetchKeywordResult, FetchPageOptions, FetchPageResult, type Filter, type GSCQueryBuilder, type GSCResult, type GSCRow, GSC_QUOTAS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, IndexStatusResult, IndexingMetadata, IndexingNotificationType, IndexingResult, InspectUrlIndexResponse, InspectUrlResult, KeywordCluster, KeywordData, KeywordRow, MobileUsabilityResult, MonthlyData, MoverData, MoversInput, MoversOptions, MoversResult, MoversSortMetric, OpportunityFactors, OpportunityOptions, OpportunityResult, OpportunitySortMetric, OpportunityWeights, Page, PageData, PageRow, Period, PublishUrlNotificationResponse, QueryOptions, QueryPageRow, QueryResultRow, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, SearchAppearanceData, SeasonalityMetric, SeasonalityOptions, SeasonalityResult, Site, SiteAnalytics, SortOrder, StreamRow, StrikingDistanceOptions, StrikingDistanceResult, StrikingDistanceSortMetric, UrlInspectionResult, UrlNotificationMetadata, YoYComparisonOptions, YoYComparisonResult, YoYMetrics, ZeroClickOptions, ZeroClickResult, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeError, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, analyzeZeroClick, and, batchInspectUrls, batchRequestIndexing, between, collectStream, contains, _default as countries, country, createAuth, createFetch, createQueryBody, createSorter, currentPstDate, date, dayjs, dayjsPst, daysAgo, deleteSitemap, device, eq, extractDateRange, fetchAnalyticsWithComparison, fetchCountries, fetchCountriesWithComparison, fetchDates, fetchDatesWithComparison, fetchDevices, fetchDevicesWithComparison, fetchKeyword, fetchKeywords, fetchKeywordsWithComparison, fetchPage, fetchPages, fetchPagesWithComparison, fetchSearchAppearance, fetchSearchAppearanceWithComparison, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, fetchYoYComparison, formatDateGsc, formatErrorForCli, getErrorCode, getErrorMessage, getIndexingMetadata, getRetryAfter, googleSearchConsole, gsc, gt, gte, inArray, inspectUrl, isAuthError, isQuotaError, isRateLimitError, like, lt, lte, ne, not, notRegex, num, or, page, percentDifference, query, queryRecursive, queryRecursiveStream, regex, requestIndexing, searchAppearance, submitSitemap, today, withDataType, withFinalData, withFreshData, withPropertyAggregation, withSearchAppearance };
+export { ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, DataRow, DimensionFilter, DimensionFilterGroup, ErrorInfo, GSC_QUOTAS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, GscdumpApiOptions, IndexStatusResult, IndexingMetadata, IndexingNotificationType, IndexingResult, InspectUrlIndexResponse, InspectUrlResult, MobileUsabilityResult, Period, PublishUrlNotificationResponse, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, UrlInspectionResult, UrlNotificationMetadata, analyzeError, batchInspectUrls, batchRequestIndexing, createAuth, createFetch, deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, getErrorCode, getErrorMessage, getIndexingMetadata, getRetryAfter, googleSearchConsole, gscdumpApi, inspectUrl, isAuthError, isQuotaError, isRateLimitError, requestIndexing, submitSitemap };