gscdump 0.4.0 → 0.5.2

package/README.md

@@ -20,6 +20,8 @@
 npm install gscdump
 ```
 
+This package is the edge-safe surface: REST client + query builder + cross-package contracts. For the storage engine (Parquet/DuckDB, planner, adapters), install [`@gscdump/engine`](../engine). For analyzers, install [`@gscdump/analysis`](../analysis).
+
 ## Usage
 
 ```ts
@@ -154,12 +156,12 @@ const cannibalization = analyzeCannibalization(keywordPageData)
 
 **Utils:** `formatDateGsc`, `percentDifference`
 
-## Related Packages
+## Related
 
-- [`@gscdump/cli`](../cli) - CLI for dump, sync, compare, analyze
-- [`@gscdump/mcp`](../mcp) - MCP server for AI agents
-- [`@gscdump/db`](../db) - SQLite persistence
-- [`@gscdump/query`](../query) - Unified data provider
+- [`@gscdump/cli`](../cli) — CLI: `sync`, `query`, `dump`, `analyze`, `mcp`, `store` admin.
+- [`@gscdump/engine`](../engine) — Append-only Parquet/DuckDB storage engine.
+- [`@gscdump/analysis`](../analysis) — SEO analyzers (row-based + DuckDB-native + D1-ready).
+- [`@gscdump/nuxt-analytics`](../nuxt-analytics) — Nuxt layer wrapping the full stack.
 
 ## License
 

package/dist/contracts.d.mts

@@ -0,0 +1,136 @@
+declare const _default: {
+  name: string;
+  'alpha-2': string;
+  'alpha-3': string;
+  'country-code': string;
+}[];
+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";
+  readonly DISCOVER: "discover";
+  readonly GOOGLE_NEWS: "googleNews";
+};
+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];
+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;
+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 Filter<C = object> {
+  readonly __filterBrand: 'gscdump.Filter';
+  readonly _constraints: C;
+  readonly _filters: InternalFilter[];
+  readonly _nestedGroups?: Filter<any>[];
+  readonly _groupType?: 'and' | 'or';
+}
+type Metric = 'clicks' | 'impressions' | 'ctr' | 'position';
+interface BuilderState {
+  dimensions: Dimension[];
+  metrics?: Metric[];
+  filter?: Filter<any>;
+  orderBy?: {
+    column: Metric | 'date';
+    dir: 'asc' | 'desc';
+  };
+  rowLimit?: number;
+  startRow?: number;
+}
+/** Logical table / dataset identifier. Canonical across query builder + storage engine. */
+type TableName = 'pages' | 'keywords' | 'countries' | 'devices' | 'page_keywords' | 'search_appearance';
+/** Untyped row shape crossing storage/query boundaries. */
+type Row = Record<string, unknown>;
+type ColumnType = 'DATE' | 'VARCHAR' | 'INTEGER' | 'BIGINT' | 'DOUBLE';
+interface ColumnDef {
+  name: string;
+  type: ColumnType;
+  nullable: boolean;
+}
+interface TableSchema {
+  name: TableName;
+  columns: ColumnDef[];
+  sortKey: string[];
+  /**
+   * Monotonically increasing version. Tagged onto every manifest entry written
+   * for this table; bump when columns are added/removed/retyped so readers can
+   * detect stale on-disk data.
+   */
+  version: number;
+}
+/** Tenant identity for multi-user / multi-site storage. */
+interface TenantCtx {
+  userId: string;
+  siteId?: string;
+}
+type AnalysisTool = 'striking-distance' | 'opportunity' | 'movers' | 'decay' | 'zero-click' | 'brand' | 'cannibalization' | 'clustering' | 'concentration' | 'seasonality' | 'trends' | 'ctr-anomaly' | 'position-volatility' | 'long-tail' | 'intent-atlas' | 'query-migration' | 'bayesian-ctr' | 'stl-decompose' | 'change-point' | 'bipartite-pagerank' | 'survival' | 'position-distribution' | 'ctr-curve' | 'dark-traffic' | 'content-velocity' | 'keyword-breadth' | 'device-gap' | 'data-query' | 'data-detail';
+interface AnalysisParams {
+  type: AnalysisTool;
+  startDate?: string;
+  endDate?: string;
+  prevStartDate?: string;
+  prevEndDate?: string;
+  brandTerms?: string[];
+  limit?: number;
+  offset?: number;
+  /** Sort column. Each analyzer enforces its own whitelist. */
+  sortBy?: string;
+  /** Sort direction. Default per-analyzer. */
+  sortDir?: 'asc' | 'desc';
+  minPosition?: number;
+  maxPosition?: number;
+  minImpressions?: number;
+  maxCtr?: number;
+  minPages?: number;
+  maxPositionSpread?: number;
+  minClusterSize?: number;
+  clusterBy?: 'prefix' | 'intent' | 'both';
+  dimension?: 'pages' | 'keywords';
+  topN?: number;
+  metric?: 'clicks' | 'impressions';
+  changeThreshold?: number;
+  minPreviousClicks?: number;
+  threshold?: number;
+  weeks?: number;
+  minWeeksWithData?: number;
+  /** content-velocity lookback window in days (max 365, default 90). */
+  days?: number;
+  /** data-query / data-detail primary BuilderState. */
+  q?: BuilderState;
+  /** data-query / data-detail optional comparison-period BuilderState. */
+  qc?: BuilderState;
+  /** data-query comparison filter applied to joined current/previous rows. */
+  comparisonFilter?: 'new' | 'lost' | 'improving' | 'declining';
+}
+interface AnalysisResult {
+  results: Record<string, unknown>[];
+  meta: Record<string, unknown>;
+}
+export { AnalysisParams, AnalysisResult, AnalysisTool, ColumnDef, ColumnType, Row, type TableName, TableSchema, TenantCtx };

package/dist/contracts.mjs

@@ -0,0 +1 @@
+export {};

package/dist/driver.d.mts

@@ -0,0 +1,78 @@
+/**
+ * Driver contracts: cross-package shapes returned by GSC API drivers
+ * (live REST, cloud-bridged, in-memory test doubles). Consumers (cloud SDK,
+ * MCP server, test fixtures) bind against these contracts so a driver swap
+ * doesn't ripple through call sites.
+ *
+ * Edge-safe: no engine imports, no `node:*`. Driver shapes describe data
+ * returned over the wire, so they belong with the REST client surface, not
+ * the storage engine.
+ */
+interface DriverSite {
+  siteUrl: string;
+  permissionLevel: string;
+}
+interface DriverSiteWithSync extends DriverSite {
+  siteId: string;
+  syncStatus: string | null;
+  syncProgress: {
+    total: number;
+    completed: number;
+    percent: number;
+  };
+  lastSyncAt: number | null;
+  newestDateSynced: string | null;
+  oldestDateSynced: string | null;
+}
+interface DriverQueryParams {
+  startDate: string;
+  endDate: string;
+  dimensions?: string[];
+  rowLimit?: number;
+  startRow?: number;
+  searchType?: string;
+  filters?: Array<{
+    dimension: string;
+    operator: string;
+    expression: string;
+  }>;
+}
+interface DriverQueryRow {
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+  [key: string]: unknown;
+}
+interface DriverQueryResult {
+  rows: DriverQueryRow[];
+  meta: {
+    siteUrl: string;
+    dimensions: string[];
+    dateRange: {
+      startDate: string;
+      endDate: string;
+    };
+    rowCount: number;
+    hasMore: boolean;
+  };
+}
+interface DriverSitemap {
+  path: string;
+  type?: string;
+  isPending?: boolean;
+  errors?: number;
+  warnings?: number;
+  urlCount?: number;
+  lastDownloaded?: string | null;
+}
+interface DriverInspectResult {
+  url: string;
+  verdict: string | null;
+  coverageState: string | null;
+  indexingState: string | null;
+  lastCrawlTime: string | null;
+  isIndexed: boolean;
+  raw: unknown;
+}
+export { DriverInspectResult, DriverQueryParams, DriverQueryResult, DriverQueryRow, DriverSite, DriverSiteWithSync, DriverSitemap };

package/dist/driver.mjs

@@ -0,0 +1 @@
+export {};

package/dist/index.d.mts

@@ -1,8 +1,6 @@
 import { $Fetch, FetchOptions } from "ofetch";
-import { indexing_v3 } from "@googleapis/indexing/v3";
-import { searchconsole_v1 } from "@googleapis/searchconsole/v1";
-
-//#region src/core/types.d.ts
+import { indexing_v3 } from "@googleapis/indexing/build/v3";
+import { searchconsole_v1 } from "@googleapis/searchconsole/build/v1";
 type ApiSite = searchconsole_v1.Schema$WmxSite;
 type ApiSitemap = searchconsole_v1.Schema$WmxSitemap;
 type ApiSitemapContent = searchconsole_v1.Schema$WmxSitemapContent;
@@ -69,16 +67,12 @@ interface SiteAnalytics {
     impressions: number;
   }[];
 }
-//#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";
@@ -90,12 +84,12 @@ declare const SearchTypes: {
   readonly IMAGE: "image";
   readonly VIDEO: "video";
   readonly NEWS: "news";
+  readonly DISCOVER: "discover";
+  readonly GOOGLE_NEWS: "googleNews";
 };
 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;
@@ -110,9 +104,8 @@ interface QueryParamValueMap {
   searchType: SearchType;
 }
 type QueryParamName = keyof QueryParamValueMap;
-declare const ColumnBrand: unique symbol;
 interface Column<D extends Dimension> {
-  readonly [ColumnBrand]: D;
+  readonly __columnBrand: 'gscdump.Column';
   readonly dimension: D;
 }
 type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
@@ -125,9 +118,8 @@ interface InternalFilter {
   expression: string;
   expression2?: string;
 }
-declare const FilterBrand: unique symbol;
 interface Filter<C = object> {
-  readonly [FilterBrand]: true;
+  readonly __filterBrand: 'gscdump.Filter';
   readonly _constraints: C;
   readonly _filters: InternalFilter[];
   readonly _nestedGroups?: Filter<any>[];
@@ -140,9 +132,8 @@ type GSCRow<D extends Dimension[], C> = { [K in D[number]]: K extends keyof C ?
   position: number;
 };
 type Metric = 'clicks' | 'impressions' | 'ctr' | 'position';
-declare const MetricColumnBrand: unique symbol;
 interface MetricColumn<M extends Metric> {
-  readonly [MetricColumnBrand]: M;
+  readonly __metricColumnBrand: 'gscdump.MetricColumn';
   readonly metric: M;
 }
 interface BuilderState {
@@ -156,8 +147,6 @@ interface BuilderState {
   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;
@@ -173,8 +162,6 @@ interface GSCQueryBuilder<D extends Dimension[] = [], C = object> {
   toBody: () => SearchAnalyticsQuery;
   getState: () => BuilderState;
 }
-//#endregion
-//#region src/core/client.d.ts
 /**
  * Compatible interface with OAuth2Client from google-auth-library
  */
@@ -199,27 +186,31 @@ type Auth = string | {
   accessToken: string;
 } | AuthClient | AuthOptions;
 declare function createFetch(auth: Auth, options?: FetchOptions): $Fetch;
+/** Per-call options. `signal` cancels the in-flight request (and, for `query`, the next page too). */
+interface CallOptions {
+  signal?: AbortSignal;
+}
 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>[]>;
+  query: <D extends Dimension[], C>(siteUrl: string, builder: GSCQueryBuilder<D, C>, opts?: CallOptions) => AsyncGenerator<GSCRow<D, C>[]>;
   /** List all sites */
-  sites: () => Promise<ApiSite[]>;
+  sites: (opts?: CallOptions) => Promise<ApiSite[]>;
   /** Inspect a URL */
-  inspect: (siteUrl: string, url: string) => Promise<InspectUrlIndexResponse>;
+  inspect: (siteUrl: string, url: string, opts?: CallOptions) => 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>;
+    list: (siteUrl: string, opts?: CallOptions) => Promise<ApiSitemap[]>;
+    get: (siteUrl: string, feedpath: string, opts?: CallOptions) => Promise<ApiSitemap>;
+    submit: (siteUrl: string, feedpath: string, opts?: CallOptions) => Promise<void>;
+    delete: (siteUrl: string, feedpath: string, opts?: CallOptions) => Promise<void>;
   };
   /** Indexing API operations */
   indexing: {
-    publish: (url: string, type: 'URL_UPDATED' | 'URL_DELETED') => Promise<PublishUrlNotificationResponse>;
-    getMetadata: (url: string) => Promise<UrlNotificationMetadata>;
+    publish: (url: string, type: 'URL_UPDATED' | 'URL_DELETED', opts?: CallOptions) => Promise<PublishUrlNotificationResponse>;
+    getMetadata: (url: string, opts?: CallOptions) => Promise<UrlNotificationMetadata>;
   };
   /** @internal */
-  _rawQuery: (siteUrl: string, body: SearchAnalyticsQuery) => Promise<SearchAnalyticsResponse>;
+  _rawQuery: (siteUrl: string, body: SearchAnalyticsQuery, opts?: CallOptions) => Promise<SearchAnalyticsResponse>;
 }
 interface GoogleSearchConsoleClientOptions {
   fetchOptions?: FetchOptions;
@@ -229,8 +220,6 @@ interface GoogleSearchConsoleClientOptions {
   }) => void | Promise<void>;
 }
 declare function googleSearchConsole(auth: Auth, options?: GoogleSearchConsoleClientOptions): GoogleSearchConsoleClient;
-//#endregion
-//#region src/api/indexing.d.ts
 type IndexingNotificationType = 'URL_UPDATED' | 'URL_DELETED';
 interface IndexingResult {
   url: string;
@@ -264,8 +253,6 @@ declare function batchRequestIndexing(client: GoogleSearchConsoleClient, urls: s
   delayMs?: number;
   onProgress?: (result: IndexingResult, index: number, total: number) => void;
 }): Promise<IndexingResult[]>;
-//#endregion
-//#region src/api/inspection.d.ts
 interface InspectUrlResult {
   url: string;
   inspection?: UrlInspectionResult;
@@ -286,8 +273,6 @@ declare function batchInspectUrls(client: GoogleSearchConsoleClient, siteUrl: st
   delayMs?: number;
   onProgress?: (result: InspectUrlResult, index: number, total: number) => void;
 }): Promise<InspectUrlResult[]>;
-//#endregion
-//#region src/api/sites.d.ts
 /**
  * Fetches all sites the authenticated user has access to in Google Search Console.
  */
@@ -314,84 +299,168 @@ 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;
 }
-/**
- * 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 gscdumpApi(options: GscdumpApiOptions): GoogleSearchConsoleClient;
-//#endregion
-//#region src/core/errors.d.ts
 /**
- * GSC API error detection and formatting utilities.
- * Provides helpful messages for quota exceeded and rate limit errors.
+ * Build a row with default-zeroed metrics. Callers attach dimension keys
+ * separately (positional via `row.keys[i]` for the raw GSC API, or named via
+ * `row[dim]` for the gscdump.com REST API).
  */
-interface ErrorInfo {
-  isQuotaError: boolean;
-  isRateLimitError: boolean;
-  isAuthError: boolean;
-  code?: number;
+declare function rowWithMetricDefaults(row: {
+  clicks?: number | null;
+  impressions?: number | null;
+  ctr?: number | null;
+  position?: number | null;
+}): {
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+};
+declare function progressBar(current: number, total: number, label: string, width?: number): string;
+type GscErrorKind = 'auth-expired' | 'rate-limited' | 'not-found' | 'validation' | 'storage' | 'transport';
+type GscError = {
+  kind: 'auth-expired';
+  message: string;
+  cause: unknown;
+} | {
+  kind: 'rate-limited';
   message: string;
   retryAfter?: number;
-  suggestion: string;
-}
-/** GSC API quota limits (approximate) */
+  cause: unknown;
+} | {
+  kind: 'not-found';
+  message: string;
+  cause: unknown;
+} | {
+  kind: 'validation';
+  message: string;
+  cause: unknown;
+} | {
+  kind: 'storage';
+  message: string;
+  cause: unknown;
+} | {
+  kind: 'transport';
+  message: string;
+  status?: number;
+  cause: unknown;
+};
+/** Approximate per-day GSC API quotas, used in CLI messaging. */
 declare const GSC_QUOTAS: {
-  /** Search Analytics API: ~25,000 requests/day per project */
   readonly searchAnalytics: 25000;
-  /** URL Inspection API: ~2,000 requests/day per property */
   readonly urlInspection: 2000;
-  /** Indexing API: ~200 requests/day per property */
   readonly indexing: 200;
 };
 /**
- * Detects if an error is a quota exceeded error (403 quotaExceeded).
- */
-declare function isQuotaError(error: unknown): boolean;
-/**
- * Detects if an error is a rate limit error (429 Too Many Requests).
+ * Classify an unknown error into a `GscError` discriminated union.
+ * Transport is the catch-all — anything without a recognizable status ends up there.
  */
-declare function isRateLimitError(error: unknown): boolean;
+declare function classifyError(cause: unknown): GscError;
+/** Construct a storage-kind error from inside the analytics engine / adapters. */
+declare function storageError(message: string, cause?: unknown): GscError;
 /**
- * Detects if an error is an authentication error (401/403 without quota).
+ * String-matches an error against the signals Google returns when a token
+ * has lost access to a property (revoked, downgraded, or never had it).
+ * Cheaper than a full {@link classifyError} call when the caller only
+ * needs the permission verdict.
  */
-declare function isAuthError(error: unknown): boolean;
+declare function isPermissionDeniedError(err: unknown): boolean;
+/** CLI-facing formatter. Returns an ANSI-colored multi-line string. */
+declare function formatErrorForCli(cause: unknown): string;
+/** Milliseconds in a UTC day. Use for date arithmetic without DST surprises. */
+declare const MS_PER_DAY = 86400000;
+/** Format a Date as YYYY-MM-DD (UTC). */
+declare function toIsoDate(d: Date): string;
+/** Most recent date GSC has fully finalized data for (no further updates). */
+declare const GSC_FINALIZED_LAG_DAYS = 3;
+/** Most recent date GSC will return data for, may still be updating. */
+declare const GSC_FRESHEST_LAG_DAYS = 1;
+/** Approximate historical retention window for Search Analytics. */
+declare const GSC_RETENTION_MONTHS = 16;
+/** Today's date (YYYY-MM-DD) in PST. */
+declare function getPstDate(): string;
+/** YYYY-MM-DD for `now() - n` days, UTC. */
+declare function daysAgo(n: number): string;
+/** Most recent finalized date (3 days ago PST). */
+declare function getLatestGscDate(): string;
+/** Freshest date GSC will return (yesterday PST, may still update). */
+declare function getFreshestGscDate(): string;
 /**
- * Extracts HTTP status code from various error formats.
+ * Dates that are still pending (1-3 days ago PST). These need to be re-synced
+ * each day until they finalize.
  */
-declare function getErrorCode(error: unknown): number | undefined;
+declare function getPendingDates(): string[];
+/** All dates between two YYYY-MM-DD strings (inclusive, oldest first). */
+declare function getDateRange(startDate: string, endDate: string): string[];
+/** Default span used when chunking long backfills into batches. */
+declare const DAYS_PER_RANGE = 30;
 /**
- * Extracts error message from various error formats.
+ * Like {@link getDateRange} but skips dates outside GSC's queryable window
+ * (older than retention or newer than the freshest date).
  */
-declare function getErrorMessage(error: unknown): string;
+declare function generateGscDateRange(startDate: string, endDate: string): string[];
 /**
- * Extracts retry-after value from error headers (in seconds).
+ * Group a sorted list of dates into contiguous runs, splitting on either a
+ * gap or after `daysPerRange` dates accumulate. Useful for bucketing
+ * backfill work into bounded jobs.
  */
-declare function getRetryAfter(error: unknown): number | undefined;
-/**
- * Analyzes an error and returns structured information with suggestions.
- */
-declare function analyzeError(error: unknown): ErrorInfo;
+declare function groupIntoRanges(dates: string[], daysPerRange?: number): Array<{
+  startDate: string;
+  endDate: string;
+}>;
+/** Inclusive day count between two YYYY-MM-DD strings. */
+declare function countDays(startDate: string, endDate: string): number;
+/** Oldest date GSC retains (~16 months ago). */
+declare function getOldestGscDate(): string;
+/** Add `n` UTC days to a YYYY-MM-DD string (n may be negative). */
+declare function addDays(dateStr: string, n: number): string;
+declare function getPreviousDate(dateStr: string): string;
+declare function getNextDate(dateStr: string): string;
+/** True if `dateStr` falls within GSC's queryable window. */
+declare function isValidGscDate(dateStr: string): boolean;
+interface BackfillProgress {
+  progress: number;
+  daysAvailable: number;
+  daysSynced: number;
+  oldestGscDate: string;
+  isComplete: boolean;
+}
 /**
- * Formats an error for CLI display with color codes.
+ * Backfill progress (0-1) given the oldest + newest dates synced.
+ * Returns null when no sync data exists.
  */
-declare function formatErrorForCli(error: unknown): string;
-//#endregion
-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 };
+declare function getBackfillProgress(oldestDateSynced: string | null, newestDateSynced: string | null): BackfillProgress | null;
+declare const INDEXING_ISSUE_FILTERS: {
+  readonly canonical_mismatch: "user_canonical IS NOT NULL AND google_canonical IS NOT NULL AND user_canonical != google_canonical";
+  readonly stale_crawl: "last_crawl_time < datetime('now', '-30 days')";
+  readonly very_stale_crawl: "last_crawl_time < datetime('now', '-60 days')";
+  readonly not_indexed: "verdict IN ('FAIL', 'PARTIAL', 'NEUTRAL')";
+  readonly unknown_to_google: "coverage_state = 'URL is unknown to Google'";
+  readonly crawled_not_indexed: "coverage_state LIKE '%Crawled%not indexed%' OR coverage_state LIKE '%Discovered%not indexed%'";
+  readonly not_found: "page_fetch_state = 'NOT_FOUND' OR coverage_state = 'Not found (404)'";
+  readonly soft_404: "page_fetch_state = 'SOFT_404'";
+  readonly server_error: "page_fetch_state = 'SERVER_ERROR'";
+  readonly blocked_robots: "robots_txt_state = 'DISALLOWED'";
+  readonly noindex: "indexing_state LIKE '%noindex%' OR coverage_state LIKE '%noindex%'";
+  readonly redirect: "coverage_state = 'Page with redirect'";
+  readonly fragment_url: "url LIKE '%#%'";
+  readonly mobile_fail: "mobile_verdict IN ('FAIL', 'PARTIAL')";
+  readonly rich_results_fail: "rich_results_verdict = 'FAIL'";
+  readonly rich_results_warning: "rich_results_verdict = 'PARTIAL'";
+  readonly rich_results_pass: "rich_results_verdict = 'PASS'";
+};
+type IndexingIssueType = keyof typeof INDEXING_ISSUE_FILTERS;
+declare const INDEXING_ISSUE_LABELS: Record<IndexingIssueType, string>;
+declare const INDEXING_ISSUE_SEVERITY: Record<IndexingIssueType, 'error' | 'warning' | 'info'>;
+declare const INDEXING_DAILY_LIMIT = 2000;
+declare const INDEXING_EFFECTIVE_LIMIT = 1800;
+declare function hasGscReadScope(scopes: string | null | undefined): boolean;
+declare function hasGscWriteScope(scopes: string | null | undefined): boolean;
+declare function hasIndexingScope(scopes: string | null | undefined): boolean;
+export { ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, BackfillProgress, CallOptions, DAYS_PER_RANGE, DataRow, DimensionFilter, DimensionFilterGroup, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_QUOTAS, GSC_RETENTION_MONTHS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, GscError, GscErrorKind, GscdumpApiOptions, INDEXING_DAILY_LIMIT, INDEXING_EFFECTIVE_LIMIT, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, IndexStatusResult, IndexingIssueType, IndexingMetadata, IndexingNotificationType, IndexingResult, InspectUrlIndexResponse, InspectUrlResult, MS_PER_DAY, MobileUsabilityResult, Period, PublishUrlNotificationResponse, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, UrlInspectionResult, UrlNotificationMetadata, addDays, batchInspectUrls, batchRequestIndexing, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingMetadata, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, googleSearchConsole, groupIntoRanges, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, inspectUrl, isPermissionDeniedError, isValidGscDate, progressBar, requestIndexing, rowWithMetricDefaults, storageError, submitSitemap, toIsoDate };