gscdump 0.1.3 → 0.3.0

package/README.md

@@ -66,7 +66,7 @@ Drizzle-style query builder with full type safety. Filter constraints flow throu
 ```ts
 import { and, between, contains, country, Country, date, device, Device, eq, gsc, inArray, page } from 'gscdump/query'
 
-const result = await gsc
+const body = gsc
   .select('page', 'query', 'device', 'country')
   .where(and(
     eq(device, Device.MOBILE),
@@ -74,14 +74,9 @@ const result = await gsc
     contains(page, '/blog/'),
     between(date, '2024-01-01', '2024-01-31')
   ))
-  .siteUrl('https://example.com')
-  .execute(client)
-
-// Fully typed results - narrowed by filters
-result.rows[0].device // type: 'MOBILE' (narrowed by eq)
-result.rows[0].country // type: 'usa' | 'gbr' (narrowed by inArray)
-result.rows[0].page // type: string (contains doesn't narrow)
-result.rows[0].clicks // type: number
+  .toBody()
+
+// Use with client.searchAnalytics.query(siteUrl, body)
 ```
 
 **With date helpers:**

package/dist/analysis/index.d.mts

@@ -0,0 +1,513 @@
+import "ofetch";
+import { indexing_v3 } from "@googleapis/indexing/v3";
+import { searchconsole_v1 } from "@googleapis/searchconsole/v1";
+
+//#region src/analysis/types.d.ts
+/**
+ * Shared types for analysis functions.
+ */
+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;
+}
+/** 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/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: KeywordRow[];
+  nonBrand: KeywordRow[];
+  summary: BrandSummary;
+}
+/**
+ * Segments keywords into brand and non-brand based on provided brand terms.
+ */
+declare function analyzeBrandSegmentation(keywords: KeywordRow[], options: BrandSegmentationOptions): BrandSegmentationResult;
+//#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: KeywordRow[];
+  totalClicks: number;
+  totalImpressions: number;
+  avgPosition: number;
+  keywordCount: number;
+}
+interface ClusteringResult {
+  clusters: KeywordCluster[];
+  unclustered: KeywordRow[];
+}
+/**
+ * Clusters keywords by intent prefix or common word prefix.
+ */
+declare function analyzeClustering(keywords: KeywordRow[], options?: ClusteringOptions): ClusteringResult;
+//#endregion
+//#region src/analysis/concentration.d.ts
+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;
+}
+interface ConcentrationInput {
+  key: string;
+  clicks: number;
+}
+/**
+ * Analyzes traffic concentration across items (pages or keywords).
+ */
+declare function analyzeConcentration(items: ConcentrationInput[], options?: ConcentrationOptions): ConcentrationResult;
+/**
+ * Page concentration analysis.
+ */
+declare function analyzePageConcentration(pages: PageRow[], options?: ConcentrationOptions): ConcentrationResult;
+/**
+ * Keyword concentration analysis.
+ */
+declare function analyzeKeywordConcentration(keywords: KeywordRow[], 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: PageRow[];
+  previous: PageRow[];
+}
+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.
+ */
+declare function analyzeDecay(input: DecayInput, options?: DecayOptions): DecayResult[];
+//#endregion
+//#region src/core/types.d.ts
+type ApiSite = searchconsole_v1.Schema$WmxSite;
+type ApiSitemap = searchconsole_v1.Schema$WmxSitemap;
+type SearchAnalyticsQuery = searchconsole_v1.Schema$SearchAnalyticsQueryRequest;
+type SearchAnalyticsResponse = searchconsole_v1.Schema$SearchAnalyticsQueryResponse;
+type InspectUrlIndexResponse = searchconsole_v1.Schema$InspectUrlIndexResponse;
+type UrlNotificationMetadata = indexing_v3.Schema$UrlNotificationMetadata;
+type PublishUrlNotificationResponse = indexing_v3.Schema$PublishUrlNotificationResponse;
+//#endregion
+//#region src/query/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 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/query/types.d.ts
+interface DimensionValueMap {
+  query: string;
+  queryCanonical: string;
+  page: string;
+  country: Country;
+  device: Device;
+  searchAppearance: string;
+  date: string;
+}
+type Dimension = keyof DimensionValueMap;
+interface QueryParamValueMap {
+  searchType: SearchType;
+}
+type QueryParamName = keyof QueryParamValueMap;
+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';
+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;
+}
+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';
+}
+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;
+};
+type Metric = 'clicks' | 'impressions' | 'ctr' | 'position';
+declare const MetricColumnBrand: unique symbol;
+interface MetricColumn<M extends Metric> {
+  readonly [MetricColumnBrand]: M;
+  readonly metric: M;
+}
+interface BuilderState {
+  dimensions: Dimension[];
+  metrics?: Metric[];
+  filter?: Filter<any>;
+  orderBy?: {
+    column: Metric | 'date';
+    dir: 'asc' | 'desc';
+  };
+  rowLimit?: number;
+  startRow?: number;
+}
+//#endregion
+//#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;
+}
+//#endregion
+//#region src/core/client.d.ts
+interface GoogleSearchConsoleClient {
+  /** 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<ApiSitemap[]>;
+    get: (siteUrl: string, feedpath: string) => Promise<ApiSitemap>;
+    submit: (siteUrl: string, feedpath: string) => Promise<void>;
+    delete: (siteUrl: string, feedpath: string) => Promise<void>;
+  };
+  /** 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>;
+}
+//#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: KeywordRow[];
+  previous: KeywordRow[];
+  /** 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[];
+}
+/**
+ * Identifies movers and shakers - keywords with significant recent changes.
+ */
+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;
+}
+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;
+}
+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;
+}
+/**
+ * Scores keywords by optimization opportunity.
+ * Composite score combining position, impressions, and CTR gap factors.
+ */
+declare function analyzeOpportunity(keywords: KeywordRow[], 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.
+ */
+declare function analyzeSeasonality(dates: DateRow[], 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;
+}
+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;
+}
+/**
+ * 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[];
+//#endregion
+//#region src/analysis/fetch.d.ts
+interface AnalysisPeriod {
+  startDate: string;
+  endDate: string;
+}
+interface ComparisonPeriod {
+  current: AnalysisPeriod;
+  previous: AnalysisPeriod;
+}
+type QueryDimension = 'keywords' | 'pages' | 'dates';
+interface QueryOptions {
+  /** Dimension to query. Default: keywords */
+  dimension?: QueryDimension;
+  /** Max rows to fetch. Default: 25000 */
+  limit?: number;
+}
+interface QueryResult {
+  keywords: KeywordRow[];
+  pages: PageRow[];
+  dates: DateRow[];
+}
+interface ComparisonQueryResult {
+  current: QueryResult;
+  previous: QueryResult;
+}
+/**
+ * Query search analytics data for a single period.
+ * Returns keywords, pages, and dates data.
+ * API calls: 3 (one per dimension)
+ */
+declare function queryAnalytics(client: GoogleSearchConsoleClient, siteUrl: string, period: AnalysisPeriod, options?: QueryOptions): Promise<QueryResult>;
+/**
+ * Query search analytics data for current and previous periods.
+ * Returns comparison data for all dimensions.
+ * API calls: 6 (3 per period)
+ */
+declare function queryComparison(client: GoogleSearchConsoleClient, siteUrl: string, periods: ComparisonPeriod, options?: QueryOptions): Promise<ComparisonQueryResult>;
+/**
+ * Fetch keywords and analyze striking distance opportunities.
+ * API calls: 1
+ */
+declare function fetchStrikingDistance(client: GoogleSearchConsoleClient, siteUrl: string, period: AnalysisPeriod, options?: StrikingDistanceOptions): Promise<StrikingDistanceResult[]>;
+/**
+ * Fetch keywords and analyze optimization opportunities.
+ * API calls: 1
+ */
+declare function fetchOpportunity(client: GoogleSearchConsoleClient, siteUrl: string, period: AnalysisPeriod, options?: OpportunityOptions): Promise<OpportunityResult[]>;
+/**
+ * Fetch keywords and analyze brand vs non-brand segmentation.
+ * API calls: 1
+ */
+declare function fetchBrandSegmentation(client: GoogleSearchConsoleClient, siteUrl: string, period: AnalysisPeriod, options: BrandSegmentationOptions): Promise<BrandSegmentationResult>;
+/**
+ * Fetch pages and analyze traffic concentration.
+ * API calls: 1
+ */
+declare function fetchPageConcentration(client: GoogleSearchConsoleClient, siteUrl: string, period: AnalysisPeriod, options?: ConcentrationOptions): Promise<ConcentrationResult>;
+/**
+ * Fetch keywords and analyze traffic concentration.
+ * API calls: 1
+ */
+declare function fetchKeywordConcentration(client: GoogleSearchConsoleClient, siteUrl: string, period: AnalysisPeriod, options?: ConcentrationOptions): Promise<ConcentrationResult>;
+/**
+ * Fetch keywords and analyze clusters.
+ * API calls: 1
+ */
+declare function fetchClustering(client: GoogleSearchConsoleClient, siteUrl: string, period: AnalysisPeriod, options?: ClusteringOptions): Promise<ClusteringResult>;
+/**
+ * Fetch dates and analyze seasonality patterns.
+ * API calls: 1
+ */
+declare function fetchSeasonality(client: GoogleSearchConsoleClient, siteUrl: string, period: AnalysisPeriod, options?: SeasonalityOptions): Promise<SeasonalityResult>;
+/**
+ * Fetch pages for both periods and analyze content decay.
+ * API calls: 2
+ */
+declare function fetchDecay(client: GoogleSearchConsoleClient, siteUrl: string, periods: ComparisonPeriod, options?: DecayOptions): Promise<DecayResult[]>;
+/**
+ * Fetch keywords for both periods and analyze movers/shakers.
+ * API calls: 2
+ */
+declare function fetchMovers(client: GoogleSearchConsoleClient, siteUrl: string, periods: ComparisonPeriod, options?: MoversOptions): Promise<MoversResult>;
+//#endregion
+export { type AnalysisPeriod, type BaseMetrics, type BrandSegmentationOptions, type BrandSegmentationResult, type BrandSummary, type ClusterType, type ClusteringOptions, type ClusteringResult, type ComparisonPeriod, type ComparisonQueryResult, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, type DateRow, type DecayInput, type DecayOptions, type DecayResult, type DecaySortMetric, type KeywordCluster, type KeywordRow, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversSortMetric, type OpportunityFactors, type OpportunityOptions, type OpportunityResult, type OpportunitySortMetric, type OpportunityWeights, type PageRow, type QueryDimension, type QueryOptions, type QueryResult, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type SortOrder, type StrikingDistanceOptions, type StrikingDistanceResult, type StrikingDistanceSortMetric, analyzeBrandSegmentation, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, createSorter, fetchBrandSegmentation, fetchClustering, fetchDecay, fetchKeywordConcentration, fetchMovers, fetchOpportunity, fetchPageConcentration, fetchSeasonality, fetchStrikingDistance, num, queryAnalytics, queryComparison };