gscdump 0.26.10 → 0.27.0

package/dist/api/index.d.mts

@@ -0,0 +1,725 @@
+import { $Fetch, FetchOptions } from "ofetch";
+import { indexing_v3 } from "@googleapis/indexing/build/v3";
+import { searchconsole_v1 } from "@googleapis/searchconsole/build/v1";
+type GscSearchAnalyticsDimension = 'page' | 'query' | 'country' | 'device' | 'date' | 'hour' | 'searchAppearance';
+type GscDataState = 'final' | 'all' | 'hourly_all';
+interface GscSearchAnalyticsMetadata {
+  /** First date (YYYY-MM-DD, PT) still being collected. Populated when dataState=`all` and grouped by `date`. */
+  first_incomplete_date?: string;
+  /** First hour (YYYY-MM-DDThh:mm:ss±hh:mm, PT) still being collected. Populated when dataState=`hourly_all` and grouped by `hour`. */
+  first_incomplete_hour?: string;
+}
+type GscSearchAnalyticsFilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
+interface GscSearchAnalyticsFilter {
+  dimension: GscSearchAnalyticsDimension;
+  expression: string;
+  operator?: GscSearchAnalyticsFilterOperator;
+}
+interface GscSearchAnalyticsFilterGroup {
+  groupType?: 'and' | 'or';
+  filters: GscSearchAnalyticsFilter[];
+}
+type GscSearchType = 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
+type GscAggregationType = 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel';
+type GscResponseAggregationType = 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel';
+interface GscSearchAnalyticsRequest {
+  startDate: string;
+  endDate: string;
+  dimensions?: GscSearchAnalyticsDimension[];
+  dimensionFilterGroups?: GscSearchAnalyticsFilterGroup[];
+  rowLimit?: number;
+  startRow?: number;
+  /** GSC search corpus. Maps to wire field `type` (the API still accepts the deprecated `searchType` alias). */
+  type?: GscSearchType;
+  dataState?: GscDataState;
+  aggregationType?: GscAggregationType;
+}
+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;
+  /** Hour bucket — ISO-8601 with PT offset, e.g. `2025-07-14T13:00:00-07:00`. Use with `dataState: 'hourly_all'`. */
+  hour: string;
+}
+type Dimension = keyof DimensionValueMap;
+interface QueryParamValueMap {
+  searchType: SearchType;
+}
+type QueryParamName = keyof QueryParamValueMap;
+interface Column<D extends Dimension> {
+  readonly __columnBrand: 'gscdump.Column';
+  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;
+}
+interface Filter<C = object> {
+  readonly __filterBrand: 'gscdump.Filter';
+  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';
+interface MetricColumn<M extends Metric> {
+  readonly __metricColumnBrand: 'gscdump.MetricColumn';
+  readonly metric: M;
+}
+interface BuilderState {
+  dimensions: Dimension[];
+  metrics?: Metric[];
+  filter?: Filter<any>;
+  prefilter?: Filter<any>;
+  orderBy?: {
+    column: Metric | 'date';
+    dir: 'asc' | 'desc';
+  };
+  rowLimit?: number;
+  startRow?: number;
+  /** GSC `dataState`. `'hourly_all'` is required when grouping by `hour`. */
+  dataState?: GscDataState;
+  /** GSC `aggregationType`. `'byNewsShowcasePanel'` requires `type=discover|googleNews` with NEWS_SHOWCASE searchAppearance. */
+  aggregationType?: GscAggregationType;
+  /** GSC search corpus. Wins over any `searchType` filter when both are set. */
+  searchType?: SearchType;
+}
+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']>;
+  prefilter: <F extends Filter<any>>(filter: F) => GSCQueryBuilder<D, C>;
+  orderBy: (col: OrderableColumn, dir: 'asc' | 'desc') => GSCQueryBuilder<D, C>;
+  limit: (n: number) => GSCQueryBuilder<D, C>;
+  offset: (n: number) => GSCQueryBuilder<D, C>;
+  dataState: (state: GscDataState) => GSCQueryBuilder<D, C>;
+  aggregationType: (type: GscAggregationType) => GSCQueryBuilder<D, C>;
+  /** GSC search corpus (`type` on the wire). Equivalent to filtering by `searchType`. */
+  type: (t: GscSearchType) => GSCQueryBuilder<D, C>;
+  toBody: () => GscSearchAnalyticsRequest;
+  getState: () => BuilderState;
+}
+type ApiSite = searchconsole_v1.Schema$WmxSite;
+type ApiSitemap = searchconsole_v1.Schema$WmxSitemap;
+type ApiSitemapContent = searchconsole_v1.Schema$WmxSitemapContent;
+type SearchAnalyticsQuery = searchconsole_v1.Schema$SearchAnalyticsQueryRequest;
+type SearchAnalyticsResponse = searchconsole_v1.Schema$SearchAnalyticsQueryResponse;
+type DataRow = searchconsole_v1.Schema$ApiDataRow;
+type DimensionFilter = searchconsole_v1.Schema$ApiDimensionFilter;
+type DimensionFilterGroup = searchconsole_v1.Schema$ApiDimensionFilterGroup;
+type UrlInspectionResult = searchconsole_v1.Schema$UrlInspectionResult;
+type IndexStatusResult = searchconsole_v1.Schema$IndexStatusInspectionResult;
+type MobileUsabilityResult = searchconsole_v1.Schema$MobileUsabilityInspectionResult;
+type RichResultsResult = searchconsole_v1.Schema$RichResultsInspectionResult;
+type InspectUrlIndexResponse = searchconsole_v1.Schema$InspectUrlIndexResponse;
+type UrlNotificationMetadata = indexing_v3.Schema$UrlNotificationMetadata;
+type PublishUrlNotificationResponse = indexing_v3.Schema$PublishUrlNotificationResponse;
+type RequiredNonNullable<T> = Required<Exclude<T, null | undefined>>;
+interface Site extends Required<Omit<ApiSite, 'siteUrl'>> {
+  siteUrl: string;
+}
+interface Period {
+  start: Date | string;
+  end: Date | string;
+}
+interface ResolvedAnalyticsRange {
+  period: Period;
+  prevPeriod?: Period;
+}
+interface SiteAnalytics {
+  analytics: {
+    period: {
+      totalClicks: number;
+      totalImpressions: number;
+    };
+    prevPeriod: {
+      totalClicks: number;
+      totalImpressions: number;
+    };
+  };
+  sitemaps: ApiSitemap[];
+  indexedUrls: string[];
+  period: {
+    url: string;
+    clicks: number;
+    clicksPercent: number;
+    prevClicks: number;
+    impressions: number;
+    impressionsPercent: number;
+    prevImpressions: number;
+  }[];
+  keywords: {
+    keyword: string;
+    position: number;
+    prevPosition: number;
+    positionPercent: number;
+    ctr: number;
+    ctrPercent: number;
+    prevCtr: number;
+    clicks: number;
+  }[];
+  graph: {
+    keys?: undefined;
+    time: string;
+    clicks: number;
+    impressions: number;
+  }[];
+}
+type VerificationMethod = 'META' | 'FILE' | 'DNS_TXT' | 'DNS_CNAME' | 'ANALYTICS' | 'TAG_MANAGER';
+type VerificationSiteType = 'SITE' | 'INET_DOMAIN' | 'ANDROID_APP';
+interface VerificationSite {
+  type: VerificationSiteType;
+  identifier: string;
+}
+interface VerificationToken {
+  method: string;
+  token: string;
+}
+interface VerificationWebResource {
+  id?: string;
+  site: VerificationSite;
+  owners?: string[];
+}
+/**
+ * Compatible interface with OAuth2Client from google-auth-library
+ */
+interface AuthClient {
+  credentials?: {
+    access_token?: string | null;
+    refresh_token?: string | null;
+    expiry_date?: number | null;
+  };
+  getAccessToken: () => Promise<{
+    token?: string | null;
+  }>;
+}
+interface AuthOptions {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+declare function createAuth(options: AuthOptions): AuthClient;
+/** Auth can be a token string, object with accessToken, or OAuth2Client-like object with credentials */
+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;
+}
+/** Generator return value for `client.query` — exposes API response metadata plus the resolved aggregation type Google actually used (may differ from the requested `aggregationType: 'auto'`). */
+interface QueryReturn {
+  metadata?: GscSearchAnalyticsMetadata;
+  /** Aggregation type Google actually used. Useful when requesting `auto` to know if rows were aggregated `byPage` vs `byProperty`. */
+  responseAggregationType?: GscResponseAggregationType;
+}
+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>, opts?: CallOptions) => AsyncGenerator<GSCRow<D, C>[], QueryReturn>;
+  /**
+   * List all sites. Also exposes write ops as `client.sites.add(siteUrl)` and
+   * `client.sites.delete(siteUrl)`. Calling `client.sites()` is equivalent to
+   * `client.sites.list()`.
+   */
+  sites: ((opts?: CallOptions) => Promise<ApiSite[]>) & {
+    list: (opts?: CallOptions) => Promise<ApiSite[]>; /** Retrieve a single property (with permission level). 404 if not in the user's account. */
+    get: (siteUrl: string, opts?: CallOptions) => Promise<ApiSite>; /** Add a property in unverified state. Caller must verify ownership separately. */
+    add: (siteUrl: string, opts?: CallOptions) => Promise<void>; /** Remove a property from the user's account. */
+    delete: (siteUrl: string, opts?: CallOptions) => Promise<void>;
+  };
+  /** Site Verification API (siteverification.googleapis.com). Required to flip a property from unverified to verified. */
+  verification: {
+    /** Returns the token to place on the site/DNS, plus the resolved method. */getToken: (params: {
+      site: VerificationSite;
+      verificationMethod: VerificationMethod;
+    }, opts?: CallOptions) => Promise<VerificationToken>; /** Triggers Google to fetch + validate; returns the verified WebResource. */
+    insert: (params: {
+      site: VerificationSite;
+      verificationMethod: VerificationMethod;
+    }, opts?: CallOptions) => Promise<VerificationWebResource>;
+    list: (opts?: CallOptions) => Promise<VerificationWebResource[]>;
+    get: (id: string, opts?: CallOptions) => Promise<VerificationWebResource>;
+    delete: (id: string, opts?: CallOptions) => Promise<void>;
+  };
+  /** Inspect a URL. `languageCode` is a BCP-47 tag for translating result strings; omit to let Google pick. */
+  inspect: (siteUrl: string, url: string, opts?: CallOptions & {
+    languageCode?: string;
+  }) => Promise<InspectUrlIndexResponse>;
+  /** Sitemap operations */
+  sitemaps: {
+    /** List sitemaps. Pass `sitemapIndex` to list children of a sitemap-index file. */list: (siteUrl: string, opts?: CallOptions & {
+      sitemapIndex?: string;
+    }) => 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', opts?: CallOptions) => Promise<PublishUrlNotificationResponse>;
+    getMetadata: (url: string, opts?: CallOptions) => Promise<UrlNotificationMetadata>;
+  };
+  /** @internal */
+  _rawQuery: (siteUrl: string, body: SearchAnalyticsQuery, opts?: CallOptions) => Promise<SearchAnalyticsResponse>;
+}
+interface GoogleSearchConsoleClientOptions {
+  fetchOptions?: FetchOptions;
+  fetch?: $Fetch;
+  onRateLimited?: (context: {
+    response: Response;
+  }) => void | Promise<void>;
+}
+declare function googleSearchConsole(auth: Auth, options?: GoogleSearchConsoleClientOptions): GoogleSearchConsoleClient;
+interface GscdumpApiOptions {
+  /** API key (gsd_user_xxx or gsd_prod_xxx) */
+  apiKey: string;
+  /** Base URL (defaults to https://gscdump.com) */
+  baseUrl?: string;
+}
+declare function gscdumpApi(options: GscdumpApiOptions): GoogleSearchConsoleClient;
+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;
+  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: {
+  readonly searchAnalytics: 25000;
+  readonly urlInspection: 2000;
+  readonly indexing: 200;
+};
+/**
+ * Classify an unknown error into a `GscError` discriminated union.
+ * Transport is the catch-all — anything without a recognizable status ends up there.
+ */
+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;
+/**
+ * Re-raises a `GscError` value as an `Error`, preserving its `cause` for
+ * stack-walking and stashing the original union under `.gscError`. Pairs with
+ * `unwrapResult` from `gscdump/result` so a `fooResult(): Result<A, GscError>`
+ * core can be wrapped by a throwing `foo()` without losing the typed error.
+ */
+declare function gscErrorToException(error: GscError): Error;
+interface GscApiErrorInfo {
+  code: number;
+  message: string;
+  reason?: string;
+  status?: string;
+}
+declare function parseGoogleError(text: string, httpStatus?: number): GscApiErrorInfo;
+declare class GscApiError extends Error {
+  info: GscApiErrorInfo;
+  constructor(message: string, info: GscApiErrorInfo);
+}
+/**
+ * Returns a handler that re-throws `unknown` as a `GscApiError` prefixed with
+ * `prefix`. Recognises `ofetch` `FetchError` (parses `err.data` as Google JSON
+ * via `parseGoogleError`); passes through existing `GscApiError`; re-throws
+ * anything else as-is.
+ */
+declare function rethrowAsGscApiError(prefix: string): (err: unknown) => never;
+/**
+ * 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 isPermissionDeniedError(err: unknown): boolean;
+/** CLI-facing formatter. Returns an ANSI-colored multi-line string. */
+declare function formatErrorForCli(cause: unknown): string;
+interface GscPropertyCandidate {
+  siteUrl?: string | null;
+  permissionLevel?: string | null;
+}
+declare function isVerifiedGscProperty(property?: GscPropertyCandidate | null): boolean;
+declare function isVerifiedGscPermission(level: string | null | undefined): boolean;
+/**
+ * Does `propertyUrl` cover `targetDomain`? Matches sc-domain (exact or
+ * subdomain) and URL-prefix (host equality) without scheme/www noise.
+ */
+declare function gscPropertyMatchesTarget(targetDomain: string, propertyUrl: string | null | undefined): boolean;
+/**
+ * Convenience: match `siteUrl` against `gscSiteUrl` directly (extracts the
+ * hostname from `siteUrl` first).
+ */
+declare function matchGscSite(siteUrl: string | null | undefined, gscSiteUrl: string | null | undefined): boolean;
+/**
+ * Pick the best GSC property for a hostname from a candidate list. "Best":
+ *   1. Verified Domain property (widest + readable)
+ *   2. Verified URL-prefix property (narrower + readable)
+ *   3. Unverified Domain property (returned as a fallback so callers can
+ *      surface the verification gap to the user)
+ *   4. Unverified URL-prefix property (same caveat)
+ *
+ * Without this ranking, naively picking the first match would register an
+ * unverified property and leave the site stuck with zero data.
+ */
+declare function pickBestGscProperty<T extends GscPropertyCandidate>(origin: string, availableSites: readonly T[]): T | undefined;
+/**
+ * Richer best-property selection that also returns the matched domain and
+ * URL candidates separately, so callers can show "we matched on X domain
+ * property and Y URL-prefix property" diagnostics.
+ */
+declare function findBestGscProperty<T extends GscPropertyCandidate>(targetDomain: string, properties: readonly T[]): {
+  matchedSite: T | null;
+  domainProperty: T | null;
+  urlProperty: T | null;
+};
+declare function findExactGscProperty<T extends GscPropertyCandidate>(propertyUrl: string, properties: readonly T[]): T | null;
+declare function formatGscPropertyCandidates(candidates: ReadonlyArray<GscPropertyCandidate | null | undefined>): string;
+declare const URL_INSPECTION_DAILY_LIMIT = 2000;
+declare const URL_INSPECTION_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;
+interface ParsedGscSiteUrl {
+  /** Original, canonical GSC property URL. */
+  label: string;
+  /** Bare hostname, stripped of protocol / sc-domain prefix / path. */
+  hostname: string;
+  /** Human-friendly label: scheme stripped, trailing slash trimmed, path retained. */
+  displayLabel: string;
+  propertyType: 'domain' | 'url-prefix';
+  isDomain: boolean;
+}
+declare function parseGscSiteUrl(siteUrl: string): ParsedGscSiteUrl;
+/**
+ * Comparison-canonical form of a GSC property URL. Strips `sc-domain:`,
+ * protocol, leading `www.`, trailing slash, and lowercases. Use when matching
+ * the same logical site across `https://www.example.com/` vs
+ * `sc-domain:example.com` vs bare hostnames — properties Google sometimes
+ * returns in different shapes for the same site.
+ */
+declare function normalizeGscSiteUrl(siteUrl: string): string;
+/**
+ * Normalize a user-input URL/hostname into a canonical registration target.
+ * Returns lowercase hostname stripped of protocol, or null if unparseable.
+ */
+declare function normalizeRegistrationTarget(inputUrl: string): string | null;
+interface DiscoverSitemapOptions {
+  /** User-Agent sent on the discovery requests. */
+  userAgent?: string;
+  /** AbortSignal threaded through fetches; defaults to a 10s timeout per call. */
+  signal?: AbortSignal;
+}
+/**
+ * Try to discover a sitemap for `domain` by checking robots.txt for a
+ * `Sitemap:` directive, then a small set of common paths. Returns the first
+ * URL that responds with a 2xx, or `null`.
+ */
+declare function discoverSitemap(domain: string, options?: DiscoverSitemapOptions): Promise<string | null>;
+interface FetchSitemapUrlsOptions extends DiscoverSitemapOptions {
+  /** Maximum nested sitemap-index depth to follow. Default 3. */
+  maxDepth?: number;
+  /** Stop after this many URLs (across all nested sitemaps). Default unlimited. */
+  limit?: number;
+}
+/**
+ * Fetch a sitemap (or sitemap index) and return the list of `<loc>` URLs.
+ * Sitemap-index files are followed up to `maxDepth` levels. Duplicates are
+ * de-duplicated. The XML parser is regex-based — it handles the common
+ * `<loc>https://...</loc>` shape but doesn't validate the schema.
+ */
+declare function fetchSitemapUrls(sitemapUrl: string, options?: FetchSitemapUrlsOptions): Promise<string[]>;
+/**
+ * Equivalence key for matching two URLs that point at the same resource
+ * across protocol (http/https), www. prefix, trailing slash, and casing.
+ * Returns `null` for unparseable input.
+ *
+ * Example: `https://www.Example.com/Foo/` → `example.com/foo`
+ */
+declare function urlMatchKey(url: string): string | null;
+/**
+ * Batch runner with optional concurrency, inter-call delay, and progress.
+ * Used by batchRequestIndexing / batchInspectUrls. Defaults to sequential
+ * (concurrency = 1) because the underlying APIs rate-limit aggressively;
+ * callers that know their quota headroom can opt into parallelism.
+ */
+declare function runSequentialBatch<I, R>(items: I[], operation: (item: I, index: number) => Promise<R>, options?: {
+  delayMs?: number;
+  concurrency?: number;
+  onProgress?: (result: R, index: number, total: number) => void;
+}): Promise<R[]>;
+type IndexingNotificationType = 'URL_UPDATED' | 'URL_DELETED';
+interface IndexingResult {
+  url: string;
+  type: IndexingNotificationType;
+  notifyTime?: string;
+}
+interface IndexingMetadata {
+  url: string;
+  latestUpdate?: indexing_v3.Schema$UrlNotificationMetadata;
+  latestRemove?: indexing_v3.Schema$UrlNotificationMetadata;
+}
+/**
+ * Request Google to index or remove a URL via the Indexing API.
+ * Note: The Indexing API officially supports only job posting and livestream content,
+ * but can be used for any URL with varying success.
+ */
+declare function requestIndexing(client: GoogleSearchConsoleClient, url: string, options?: {
+  type?: IndexingNotificationType;
+}): Promise<IndexingResult>;
+/**
+ * Get the indexing notification metadata for a URL.
+ * Returns when Google was last notified about updates/removals.
+ */
+declare function getIndexingMetadata(client: GoogleSearchConsoleClient, url: string): Promise<IndexingMetadata>;
+/**
+ * Batch request indexing for multiple URLs with rate limiting.
+ * Returns results for each URL.
+ */
+declare function batchRequestIndexing(client: GoogleSearchConsoleClient, urls: string[], options?: {
+  type?: IndexingNotificationType;
+  delayMs?: number;
+  concurrency?: number;
+  onProgress?: (result: IndexingResult, index: number, total: number) => void;
+}): Promise<IndexingResult[]>;
+interface InspectUrlResult {
+  url: string;
+  inspection?: UrlInspectionResult;
+  isIndexed: boolean;
+}
+/**
+ * Inspects a URL in Google Search Console to check its indexing status.
+ */
+declare function inspectUrl(client: GoogleSearchConsoleClient, siteUrl: string, inspectionUrl: string): Promise<{
+  inspection: UrlInspectionResult | undefined;
+  isIndexed: boolean;
+}>;
+/**
+ * Batch inspect multiple URLs with rate limiting.
+ * Returns inspection results for each URL.
+ */
+declare function batchInspectUrls(client: GoogleSearchConsoleClient, siteUrl: string, urls: string[], options?: {
+  delayMs?: number;
+  concurrency?: number;
+  onProgress?: (result: InspectUrlResult, index: number, total: number) => void;
+}): Promise<InspectUrlResult[]>;
+interface ParsedIndexingResult {
+  url: string;
+  verdict: string | null;
+  coverageState: string | null;
+  indexingState: string | null;
+  robotsTxtState: string | null;
+  pageFetchState: string | null;
+  lastCrawlTime: string | null;
+  crawlingUserAgent: string | null;
+  userCanonical: string | null;
+  googleCanonical: string | null;
+  sitemaps: string | null;
+  referringUrls: string | null;
+  mobileVerdict: string | null;
+  mobileIssues: string | null;
+  richResultsVerdict: string | null;
+  richResultsItems: string | null;
+  ampVerdict: string | null;
+  ampUrl: string | null;
+  ampIndexingState: string | null;
+  ampIndexStatusVerdict: string | null;
+  ampRobotsTxtState: string | null;
+  ampPageFetchState: string | null;
+  ampLastCrawlTime: string | null;
+  ampIssues: string | null;
+  inspectionResultLink: string | null;
+}
+declare function inspectUrlFlat(client: GoogleSearchConsoleClient, siteUrl: string, inspectionUrl: string): Promise<ParsedIndexingResult>;
+type InspectionPriority = 'high' | 'medium' | 'low';
+declare function getNextCheckPriority(result: Pick<ParsedIndexingResult, 'verdict'>): InspectionPriority;
+/** Next-check unix seconds for a given priority. */
+declare function getNextCheckAfter(priority: InspectionPriority): number;
+declare function canUseUrlInspection(permissionLevel: string | null | undefined): boolean;
+declare function grantedScopeList(scopes: string | null | undefined): string[];
+type IndexingIneligibleReason = 'missing_indexing_scope' | 'insufficient_gsc_permission';
+interface IndexingEligibility {
+  indexingEligible: boolean;
+  indexingIneligibleReason?: IndexingIneligibleReason;
+  indexingPermissionLevel?: string | null;
+  grantedScopes?: string[];
+}
+declare function getIndexingEligibility(grantedScopes: string | null | undefined, permissionLevel: string | null | undefined): IndexingEligibility;
+interface Ok<A> {
+  readonly ok: true;
+  readonly value: A;
+}
+interface Err<E> {
+  readonly ok: false;
+  readonly error: E;
+}
+type Result<A, E> = Ok<A> | Err<E>;
+interface OAuthTokens {
+  accessToken: string;
+  /** Unix seconds. */
+  expiresAt: number;
+}
+/**
+ * Errors-as-values core for {@link refreshAccessToken}: returns a classified
+ * `GscError` instead of throwing, so token-storage callers can branch on
+ * `error.kind` — `auth-expired` (the refresh token is permanently bad, re-auth)
+ * vs `transport` (transient, safe to retry later) — rather than string-matching.
+ */
+declare function refreshAccessTokenResult(refreshToken: string, clientId: string, clientSecret: string): Promise<Result<OAuthTokens, GscError>>;
+/**
+ * Exchange a refresh token for an access token. Retries transient network
+ * failures; surfaces HTTP failures (invalid_grant, etc.) immediately as
+ * `GscApiError` so callers can mark the refresh token as bad.
+ */
+declare function refreshAccessToken(refreshToken: string, clientId: string, clientSecret: string): Promise<OAuthTokens>;
+/**
+ * Errors-as-values core for {@link exchangeAuthCode}: same `auth-expired` vs
+ * `transport` classification as {@link refreshAccessTokenResult}.
+ */
+declare function exchangeAuthCodeResult(code: string, clientId: string, clientSecret: string, redirectUri: string): Promise<Result<OAuthTokens & {
+  refreshToken?: string;
+}, GscError>>;
+/**
+ * Exchange an authorization code (from the OAuth consent redirect) for
+ * access + refresh tokens. Same retry / surface model as `refreshAccessToken`.
+ */
+declare function exchangeAuthCode(code: string, clientId: string, clientSecret: string, redirectUri: string): Promise<OAuthTokens & {
+  refreshToken?: string;
+}>;
+/**
+ * Fetches all sites the authenticated user has access to in Google Search Console.
+ */
+declare function fetchSites(client: GoogleSearchConsoleClient): Promise<ApiSite[]>;
+/**
+ * Fetches all verified sites with their sitemaps from Google Search Console.
+ */
+declare function fetchSitesWithSitemaps(client: GoogleSearchConsoleClient): Promise<(Site & {
+  sitemaps: ApiSitemap[];
+})[]>;
+/**
+ * Fetches all sitemaps for a site.
+ */
+declare function fetchSitemaps(client: GoogleSearchConsoleClient, siteUrl: string): Promise<ApiSitemap[]>;
+/**
+ * Fetches a specific sitemap.
+ */
+declare function fetchSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<ApiSitemap>;
+/**
+ * Submits a sitemap to Google Search Console.
+ */
+declare function submitSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<void>;
+/**
+ * Deletes a sitemap from Google Search Console.
+ */
+declare function deleteSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<void>;
+/**
+ * Add a property to the user's Search Console account.
+ *
+ * Note: this only registers the property in an unverified state. Ownership
+ * must be proven via the Site Verification API (see `verifySite`) before any
+ * data is accessible.
+ */
+declare function addSite(client: GoogleSearchConsoleClient, siteUrl: string): Promise<void>;
+/**
+ * Remove a property from the user's Search Console account.
+ */
+declare function deleteSite(client: GoogleSearchConsoleClient, siteUrl: string): Promise<void>;
+/**
+ * Resolve a Search Console site URL (`https://example.com/` or
+ * `sc-domain:example.com`) to the Site Verification API's site shape.
+ */
+declare function siteUrlToVerificationSite(siteUrl: string): VerificationSite;
+/**
+ * Methods valid for a given site shape. SITE properties can use META/FILE/
+ * ANALYTICS/TAG_MANAGER; INET_DOMAIN must use DNS_TXT or DNS_CNAME.
+ */
+declare function verificationMethodsFor(site: VerificationSite): VerificationMethod[];
+/**
+ * Get the verification token Google expects to find on the site or DNS.
+ */
+declare function getVerificationToken(client: GoogleSearchConsoleClient, siteUrl: string, method: VerificationMethod): Promise<VerificationToken & {
+  site: VerificationSite;
+}>;
+/**
+ * Trigger Google to validate the placed token. Caller is responsible for
+ * having placed the token (HTML tag / file / DNS record) before calling.
+ */
+declare function verifySite(client: GoogleSearchConsoleClient, siteUrl: string, method: VerificationMethod): Promise<VerificationWebResource>;
+/**
+ * List all verified WebResources for the authed user.
+ */
+declare function listVerifiedSites(client: GoogleSearchConsoleClient): Promise<VerificationWebResource[]>;
+/**
+ * Fetch a single verified WebResource by id.
+ */
+declare function getVerifiedSite(client: GoogleSearchConsoleClient, id: string): Promise<VerificationWebResource>;
+/**
+ * Drop the calling user's verified ownership of a WebResource. The placed
+ * verification token (meta tag / file / DNS record) MUST be removed first,
+ * otherwise Google may auto-re-verify and the call will fail. Other owners
+ * on the property are unaffected.
+ */
+declare function unverifySite(client: GoogleSearchConsoleClient, id: string): Promise<void>;
+export { ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, CallOptions, DataRow, DimensionFilter, DimensionFilterGroup, DiscoverSitemapOptions, FetchSitemapUrlsOptions, GSC_QUOTAS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, GscApiError, GscApiErrorInfo, GscError, GscErrorKind, GscPropertyCandidate, GscdumpApiOptions, IndexStatusResult, IndexingEligibility, IndexingIneligibleReason, IndexingMetadata, IndexingNotificationType, IndexingResult, InspectUrlIndexResponse, InspectUrlResult, InspectionPriority, MobileUsabilityResult, OAuthTokens, ParsedGscSiteUrl, ParsedIndexingResult, Period, PublishUrlNotificationResponse, QueryReturn, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, URL_INSPECTION_DAILY_LIMIT, URL_INSPECTION_EFFECTIVE_LIMIT, UrlInspectionResult, UrlNotificationMetadata, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, addSite, batchInspectUrls, batchRequestIndexing, canUseUrlInspection, classifyError, createAuth, createFetch, deleteSite, deleteSitemap, discoverSitemap, exchangeAuthCode, exchangeAuthCodeResult, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, findBestGscProperty, findExactGscProperty, formatErrorForCli, formatGscPropertyCandidates, getIndexingEligibility, getIndexingMetadata, getNextCheckAfter, getNextCheckPriority, getVerificationToken, getVerifiedSite, googleSearchConsole, grantedScopeList, gscErrorToException, gscPropertyMatchesTarget, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, inspectUrl, inspectUrlFlat, isPermissionDeniedError, isVerifiedGscPermission, isVerifiedGscProperty, listVerifiedSites, matchGscSite, normalizeGscSiteUrl, normalizeRegistrationTarget, parseGoogleError, parseGscSiteUrl, pickBestGscProperty, refreshAccessToken, refreshAccessTokenResult, requestIndexing, rethrowAsGscApiError, runSequentialBatch, siteUrlToVerificationSite, storageError, submitSitemap, unverifySite, urlMatchKey, verificationMethodsFor, verifySite };