gscdump 1.3.2 → 1.4.1

package/dist/index.d.mts

@@ -1,817 +1,23 @@
-import { GscResponseAggregationType, GscSearchAnalyticsMetadata } from "./_chunks/contracts.mjs";
-import { Err, Ok, Result, err, isErr, isOk, ok, unwrapResult } from "./_chunks/result.mjs";
-import { BackfillProgress, DAYS_PER_RANGE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_RETENTION_MONTHS, MS_PER_DAY, addDays, countDays, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, groupIntoRanges, isValidGscDate, toIsoDate } from "./_chunks/gsc-dates.mjs";
-import { Dimension, GSCRow } from "./_chunks/types.mjs";
-import { GSCQueryBuilder } from "./_chunks/builder.mjs";
+import { Err, Ok, Result, err, isErr, isOk, ok, unwrapResult } from "./core/result.mjs";
+import { BackfillProgress, DAYS_PER_RANGE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_RETENTION_MONTHS, MS_PER_DAY, addDays, countDays, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, groupIntoRanges, isValidGscDate, toIsoDate } from "./core/gsc-dates.mjs";
+import { runSequentialBatch } from "./api/batch.mjs";
+import { AmpInspectionResult, AmpIssue, ApiSite, ApiSitemap, ApiSitemapContent, DataRow, DimensionFilter, DimensionFilterGroup, IndexStatusResult, InspectUrlIndexResponse, MobileUsabilityIssue, MobileUsabilityResult, Period, PublishUrlNotificationResponse, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsDetectedItem, RichResultsIssue, RichResultsItem, RichResultsResult, SearchAnalyticsMetadata, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, UrlInspectionResult, UrlNotification, UrlNotificationMetadata } from "./core/types.mjs";
+import { Auth, AuthClient, AuthOptions, CallOptions, DEFAULT_GSC_REQUEST_TIMEOUT_MS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, QueryReturn, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, createAuth, createFetch, googleSearchConsole } from "./core/client.mjs";
+import { IndexingMetadata, IndexingNotificationType, IndexingResult, batchRequestIndexing, getIndexingMetadata, requestIndexing } from "./api/indexing.mjs";
+import { BatchInspectUrlsFlatSettledOptions, IndexingEligibility, IndexingIneligibleReason, InspectUrlFlatSettledResult, InspectUrlResult, InspectionPriority, MAX_FLAT_INSPECTION_BATCH_CONCURRENCY, ParsedIndexingResult, batchInspectUrls, batchInspectUrlsFlatSettled, canUseUrlInspection, getIndexingEligibility, getNextCheckAfter, getNextCheckPriority, inspectUrl, inspectUrlFlat } from "./api/inspection.mjs";
+import { GscApiError, GscApiErrorInfo, GscError, GscErrorKind, classifyError, gscErrorToException, isPermissionDeniedError, parseGoogleError, rethrowAsGscApiError } from "./core/errors.mjs";
+import { OAuthTokenInfo, OAuthTokens, exchangeAuthCodeResult, introspectAccessToken, introspectAccessTokenResult, refreshAccessToken, revokeOAuthToken, revokeOAuthTokenResult } from "./api/oauth.mjs";
+import { FetchSitesWithSitemapsOptions, addSite, deleteSite, deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, submitSitemap } from "./api/sites.mjs";
+import { getVerificationToken, getVerifiedSite, listVerifiedSites, resolveVerificationTarget, siteUrlToVerificationSite, unverifySite, verificationMethodsFor, verifySite } from "./api/verification.mjs";
+import { INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, IndexingIssueType, KNOWN_COVERAGE_STATES, KNOWN_PAGE_FETCH_STATES, UnmappedInspectionReasons, unmappedInspectionReasons } from "./core/indexing-issues.mjs";
+import { GscPropertyCandidate, findBestGscProperty, findExactGscProperty, formatGscPropertyCandidates, gscPropertyMatchesTarget, isVerifiedGscPermission, isVerifiedGscProperty, matchGscSite, pickBestGscProperty } from "./core/property.mjs";
+import { URL_INSPECTION_EFFECTIVE_LIMIT } from "./core/quota.mjs";
+import { GSC_INDEXING_SCOPE, GSC_READ_SCOPE, GSC_SITE_VERIFICATION_SCOPE, GSC_WRITE_SCOPE, hasGoogleScope } from "./core/scope-values.mjs";
+import { hasGscReadScope, hasGscWriteScope, hasIndexingScope } from "./core/scopes.mjs";
+import { ParsedGscSiteUrl, normalizeGscSiteUrl, normalizeRegistrationTarget, parseGscSiteUrl } from "./core/site-url.mjs";
 import { normalizeUrl } from "./normalize.mjs";
+import { AccountNextAction, AccountStatus, AnalyticsNextAction, AnalyticsStatus, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSCDUMP_WRITE_ANALYTICS_SCOPE, IndexingNextAction, IndexingStatus, LifecycleError, LifecycleErrorCode, LifecycleProgress, LifecycleWebhookEnvelope, LifecycleWebhookEvent, PartnerLifecycleAccount, PartnerLifecycleResponse, PartnerLifecycleSite, PropertyNextAction, PropertyStatus, QuerySourceMode, SitemapNextAction, SitemapStatus, accountNextActions, accountStatuses, analyticsNextActions, analyticsStatuses, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, lifecycleErrorCodes, parseGrantedScopes, propertyNextActions, propertyStatuses, querySourceModes, sitemapNextActions, sitemapStatuses } from "./onboarding.mjs";
+import { DiscoverSitemapOptions, FetchSitemapUrlsOptions, discoverSitemap, fetchSitemapUrls } from "./sitemap.mjs";
 import { decodeSiteId, encodeSiteId, normalizeSiteUrl } from "./tenant.mjs";
-import { $Fetch, FetchOptions } from "ofetch";
-import { AccountNextAction, AccountStatus, AnalyticsNextAction, AnalyticsStatus, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSCDUMP_WRITE_ANALYTICS_SCOPE, IndexingNextAction, IndexingStatus, LifecycleError, LifecycleErrorCode, LifecycleProgress, LifecycleWebhookEnvelope, LifecycleWebhookEvent, PartnerLifecycleAccount, PartnerLifecycleResponse, PartnerLifecycleSite, PropertyNextAction, PropertyStatus, QuerySourceMode, SitemapNextAction, SitemapStatus, accountNextActions, accountStatuses, analyticsNextActions, analyticsStatuses, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, lifecycleErrorCodes, parseGrantedScopes, propertyNextActions, propertyStatuses, querySourceModes, sitemapNextActions, sitemapStatuses } from "@gscdump/contracts/partner";
-/**
- * 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[]>;
-/** Search Console property returned by the Sites resource. */
-interface ApiSite {
-  permissionLevel?: string | null;
-  siteUrl?: string | null;
-}
-/** Per-content-type counts returned with a sitemap. */
-interface ApiSitemapContent {
-  /** Deprecated by Google, retained because it can still appear on the wire. */
-  indexed?: string | null;
-  submitted?: string | null;
-  type?: string | null;
-}
-/** Sitemap returned by the Search Console Sitemaps resource. */
-interface ApiSitemap {
-  contents?: ApiSitemapContent[];
-  errors?: string | null;
-  isPending?: boolean | null;
-  isSitemapsIndex?: boolean | null;
-  lastDownloaded?: string | null;
-  lastSubmitted?: string | null;
-  path?: string | null;
-  type?: string | null;
-  warnings?: string | null;
-}
-/** A Search Analytics dimension filter. */
-interface DimensionFilter {
-  dimension?: string | null;
-  expression?: string | null;
-  operator?: string | null;
-}
-/** A group of Search Analytics dimension filters. */
-interface DimensionFilterGroup {
-  filters?: DimensionFilter[];
-  groupType?: string | null;
-}
-/** Raw Search Analytics request accepted by Google's REST endpoint. */
-interface SearchAnalyticsQuery {
-  aggregationType?: string | null;
-  dataState?: string | null;
-  dimensionFilterGroups?: DimensionFilterGroup[];
-  dimensions?: string[] | null;
-  endDate?: string | null;
-  rowLimit?: number | null;
-  searchType?: string | null;
-  startDate?: string | null;
-  startRow?: number | null;
-  type?: string | null;
-}
-/** Raw Search Analytics result row. */
-interface DataRow {
-  clicks?: number | null;
-  ctr?: number | null;
-  impressions?: number | null;
-  keys?: string[] | null;
-  position?: number | null;
-}
-/** Completeness metadata returned with recent Search Analytics data. */
-interface SearchAnalyticsMetadata {
-  firstIncompleteDate?: string | null;
-  firstIncompleteHour?: string | null;
-  /** Field name returned by the direct REST endpoint. */
-  first_incomplete_date?: string | null;
-  /** Field name returned by the direct REST endpoint. */
-  first_incomplete_hour?: string | null;
-}
-/** Raw Search Analytics response returned by Google's REST endpoint. */
-interface SearchAnalyticsResponse {
-  metadata?: SearchAnalyticsMetadata;
-  responseAggregationType?: string | null;
-  rows?: DataRow[];
-}
-interface AmpIssue {
-  issueMessage?: string | null;
-  severity?: string | null;
-}
-interface AmpInspectionResult {
-  ampIndexStatusVerdict?: string | null;
-  ampUrl?: string | null;
-  indexingState?: string | null;
-  issues?: AmpIssue[];
-  lastCrawlTime?: string | null;
-  pageFetchState?: string | null;
-  robotsTxtState?: string | null;
-  verdict?: string | null;
-}
-interface IndexStatusResult {
-  coverageState?: string | null;
-  crawledAs?: string | null;
-  googleCanonical?: string | null;
-  indexingState?: string | null;
-  lastCrawlTime?: string | null;
-  pageFetchState?: string | null;
-  referringUrls?: string[] | null;
-  robotsTxtState?: string | null;
-  sitemap?: string[] | null;
-  userCanonical?: string | null;
-  verdict?: string | null;
-}
-interface MobileUsabilityIssue {
-  issueType?: string | null;
-  message?: string | null;
-  severity?: string | null;
-}
-interface MobileUsabilityResult {
-  issues?: MobileUsabilityIssue[];
-  verdict?: string | null;
-}
-interface RichResultsIssue {
-  issueMessage?: string | null;
-  severity?: string | null;
-}
-interface RichResultsItem {
-  issues?: RichResultsIssue[];
-  name?: string | null;
-}
-interface RichResultsDetectedItem {
-  items?: RichResultsItem[];
-  richResultType?: string | null;
-}
-interface RichResultsResult {
-  detectedItems?: RichResultsDetectedItem[];
-  verdict?: string | null;
-}
-/** URL inspection payload returned by Search Console. */
-interface UrlInspectionResult {
-  ampResult?: AmpInspectionResult;
-  indexStatusResult?: IndexStatusResult;
-  inspectionResultLink?: string | null;
-  mobileUsabilityResult?: MobileUsabilityResult;
-  richResultsResult?: RichResultsResult;
-}
-interface InspectUrlIndexResponse {
-  inspectionResult?: UrlInspectionResult;
-}
-/** A single Indexing API notification. */
-interface UrlNotification {
-  notifyTime?: string | null;
-  type?: string | null;
-  url?: string | null;
-}
-/** Latest Indexing API notifications recorded for a URL. */
-interface UrlNotificationMetadata {
-  latestRemove?: UrlNotification;
-  latestUpdate?: UrlNotification;
-  url?: string | null;
-}
-interface PublishUrlNotificationResponse {
-  urlNotificationMetadata?: UrlNotificationMetadata;
-}
-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;
-  }[];
-}
-/** Default deadline for each direct Google API request. */
-declare const DEFAULT_GSC_REQUEST_TIMEOUT_MS = 30000;
-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>;
-  };
-  /** Direct Search Analytics API operations for callers that already have a request body. */
-  searchAnalytics: {
-    query: (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;
-type IndexingNotificationType = 'URL_UPDATED' | 'URL_DELETED';
-interface IndexingResult {
-  url: string;
-  type: IndexingNotificationType;
-  notifyTime?: string;
-}
-interface IndexingMetadata {
-  url: string;
-  latestUpdate?: UrlNotification;
-  latestRemove?: UrlNotification;
-}
-/**
- * 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, options?: CallOptions): Promise<ParsedIndexingResult>;
-/** Maximum parallel URL Inspection requests started by the settled flat batch helper. */
-declare const MAX_FLAT_INSPECTION_BATCH_CONCURRENCY = 10;
-type InspectUrlFlatSettledResult = {
-  url: string;
-  status: 'fulfilled';
-  value: ParsedIndexingResult;
-} | {
-  url: string;
-  status: 'rejected';
-  reason: unknown;
-};
-interface BatchInspectUrlsFlatSettledOptions extends CallOptions {
-  /** Delay after each request handled by a worker. Defaults to 200ms. */
-  delayMs?: number;
-  /** Number of workers. Defaults to 1 and is capped at {@link MAX_FLAT_INSPECTION_BATCH_CONCURRENCY}. */
-  concurrency?: number;
-  onProgress?: (result: InspectUrlFlatSettledResult, index: number, total: number) => void;
-}
-/**
- * Inspect URLs into the flat storage shape without failing the whole batch
- * when one URL fails. Results retain input order and include each URL so
- * callers can persist successes and classify individual failures safely.
- */
-declare function batchInspectUrlsFlatSettled(client: GoogleSearchConsoleClient, siteUrl: string, urls: readonly string[], options?: BatchInspectUrlsFlatSettledOptions): Promise<InspectUrlFlatSettledResult[]>;
-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;
-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;
-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;
-};
-/**
- * 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;
-/**
- * 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;
-interface OAuthTokens {
-  accessToken: string;
-  /** Unix seconds. */
-  expiresAt: number;
-  /** Space-delimited scopes Google granted for this token, when returned. */
-  scope?: string;
-}
-/** Normalized response from Google's access-token introspection endpoint. */
-interface OAuthTokenInfo {
-  issuedTo?: string;
-  audience?: string;
-  authorizedParty?: string;
-  userId?: string;
-  subject?: string;
-  scope?: string;
-  /** Seconds remaining when Google inspected the token. */
-  expiresIn?: number;
-  /** Unix seconds. */
-  expiresAt?: number;
-  email?: string;
-  emailVerified?: boolean;
-  accessType?: string;
-}
-/**
- * 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>;
-/**
- * Exchange an authorization code (from the OAuth consent redirect) for
- * access + refresh tokens. Same retry / surface model and `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>>;
-/** Inspect an access token without throwing on expected OAuth failures. */
-declare function introspectAccessTokenResult(accessToken: string): Promise<Result<OAuthTokenInfo, GscError>>;
-/** Throwing convenience wrapper for {@link introspectAccessTokenResult}. */
-declare function introspectAccessToken(accessToken: string): Promise<OAuthTokenInfo>;
-/** Revoke an access or refresh token without throwing on expected OAuth failures. */
-declare function revokeOAuthTokenResult(token: string): Promise<Result<void, GscError>>;
-/** Throwing convenience wrapper for {@link revokeOAuthTokenResult}. */
-declare function revokeOAuthToken(token: string): Promise<void>;
-interface FetchSitesWithSitemapsOptions {
-  /** Maximum concurrent sitemap-list requests. Defaults to 4. */
-  concurrency?: number;
-}
-/**
- * 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, options?: FetchSitesWithSitemapsOptions): 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;
-/** Resolve a Search Console property and method to Google's verification target. */
-declare function resolveVerificationTarget(siteUrl: string, method?: VerificationMethod): {
-  site: VerificationSite;
-  method: VerificationMethod;
-};
-/**
- * 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>;
-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 = 'Crawled - currently not indexed'";
-  readonly discovered_not_indexed: "coverage_state = 'Discovered - currently not indexed'";
-  readonly not_found: "page_fetch_state = 'NOT_FOUND' OR coverage_state = 'Not found (404)'";
-  readonly soft_404: "page_fetch_state = 'SOFT_404' OR coverage_state = 'Soft 404'";
-  readonly server_error: "page_fetch_state = 'SERVER_ERROR' OR coverage_state = 'Server error (5xx)'";
-  readonly access_forbidden: "page_fetch_state = 'ACCESS_FORBIDDEN' OR coverage_state = 'Blocked due to access forbidden (403)'";
-  readonly access_denied: "page_fetch_state = 'ACCESS_DENIED' OR coverage_state = 'Blocked due to unauthorized request (401)'";
-  readonly blocked_4xx: "page_fetch_state = 'BLOCKED_4XX' OR coverage_state = 'Blocked due to other 4xx issue'";
-  readonly redirect_error: "page_fetch_state = 'REDIRECT_ERROR' OR coverage_state = 'Redirect error'";
-  readonly crawl_error: "page_fetch_state IN ('INTERNAL_CRAWL_ERROR', 'INVALID_URL')";
-  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 sitemap_redirect: "coverage_state = 'Page with redirect' AND sitemaps IS NOT NULL AND sitemaps != '[]'";
-  readonly alternate_canonical: "coverage_state = 'Alternate page with proper canonical tag'";
-  readonly duplicate_no_canonical: "coverage_state = 'Duplicate without user-selected canonical'";
-  readonly page_removed: "coverage_state = 'Blocked by page removal tool'";
-  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'>;
-/**
- * Every `pageFetchState` the URL Inspection API documents. `SUCCESSFUL` and the
- * `_UNSPECIFIED` sentinel are non-faults; the rest each map to a filter above.
- */
-declare const KNOWN_PAGE_FETCH_STATES: ReadonlySet<string>;
-/**
- * Every `coverageState` string we have a bucket for, plus the indexed-state strings
- * that are not faults. Google is free to invent new prose here at any time — that's
- * exactly what {@link unmappedInspectionReasons} exists to catch.
- */
-declare const KNOWN_COVERAGE_STATES: ReadonlySet<string>;
-interface UnmappedInspectionReasons {
-  coverageStates: string[];
-  pageFetchStates: string[];
-}
-/**
- * Which reason strings in this batch of inspection results we have no bucket for.
- *
- * Pure, allocation-cheap, and safe to call on every ingest batch. A non-empty
- * result means Google reports a state the filter map cannot see — the URLs are
- * still counted in `not_indexed`, but nothing narrower, so the product will
- * under-report exactly the way it did for `ACCESS_FORBIDDEN` before this existed.
- */
-declare function unmappedInspectionReasons(rows: ReadonlyArray<{
-  coverageState?: string | null;
-  pageFetchState?: string | null;
-}>): UnmappedInspectionReasons;
-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_EFFECTIVE_LIMIT = 1800;
-type GoogleScopesInput$1 = string | readonly string[] | null | undefined;
-declare const GSC_READ_SCOPE: "https://www.googleapis.com/auth/webmasters.readonly";
-declare const GSC_WRITE_SCOPE: "https://www.googleapis.com/auth/webmasters";
-declare const GSC_INDEXING_SCOPE: "https://www.googleapis.com/auth/indexing";
-declare const GSC_SITE_VERIFICATION_SCOPE: "https://www.googleapis.com/auth/siteverification";
-declare function hasGoogleScope(scopes: GoogleScopesInput$1, scope: string): boolean;
-type GoogleScopesInput = string | readonly string[] | null | undefined;
-declare function hasGscReadScope(scopes: GoogleScopesInput): boolean;
-declare function hasGscWriteScope(scopes: GoogleScopesInput): boolean;
-declare function hasIndexingScope(scopes: GoogleScopesInput): 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;
+import { urlMatchKey } from "./url.mjs";
 export { type AccountNextAction, type AccountStatus, AmpInspectionResult, AmpIssue, type AnalyticsNextAction, type AnalyticsStatus, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, type BackfillProgress, BatchInspectUrlsFlatSettledOptions, CallOptions, DAYS_PER_RANGE, DEFAULT_GSC_REQUEST_TIMEOUT_MS, DataRow, DimensionFilter, DimensionFilterGroup, DiscoverSitemapOptions, Err, FetchSitemapUrlsOptions, FetchSitesWithSitemapsOptions, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSCDUMP_WRITE_ANALYTICS_SCOPE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_INDEXING_SCOPE, GSC_READ_SCOPE, GSC_RETENTION_MONTHS, GSC_SITE_VERIFICATION_SCOPE, GSC_WRITE_SCOPE, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, GscApiError, type GscApiErrorInfo, type GscError, type GscErrorKind, GscPropertyCandidate, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, IndexStatusResult, IndexingEligibility, IndexingIneligibleReason, IndexingIssueType, IndexingMetadata, type IndexingNextAction, IndexingNotificationType, IndexingResult, type IndexingStatus, InspectUrlFlatSettledResult, InspectUrlIndexResponse, InspectUrlResult, InspectionPriority, KNOWN_COVERAGE_STATES, KNOWN_PAGE_FETCH_STATES, type LifecycleError, type LifecycleErrorCode, type LifecycleProgress, type LifecycleWebhookEnvelope, type LifecycleWebhookEvent, MAX_FLAT_INSPECTION_BATCH_CONCURRENCY, MS_PER_DAY, MobileUsabilityIssue, MobileUsabilityResult, OAuthTokenInfo, OAuthTokens, Ok, ParsedGscSiteUrl, ParsedIndexingResult, type PartnerLifecycleAccount, type PartnerLifecycleResponse, type PartnerLifecycleSite, Period, type PropertyNextAction, type PropertyStatus, PublishUrlNotificationResponse, QueryReturn, type QuerySourceMode, RequiredNonNullable, ResolvedAnalyticsRange, Result, RichResultsDetectedItem, RichResultsIssue, RichResultsItem, RichResultsResult, SearchAnalyticsMetadata, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, type SitemapNextAction, type SitemapStatus, URL_INSPECTION_EFFECTIVE_LIMIT, UnmappedInspectionReasons, UrlInspectionResult, UrlNotification, UrlNotificationMetadata, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchInspectUrlsFlatSettled, batchRequestIndexing, canUseUrlInspection, classifyError, countDays, createAuth, createFetch, decodeSiteId, deleteSite, deleteSitemap, discoverSitemap, encodeSiteId, err, exchangeAuthCodeResult, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, findBestGscProperty, findExactGscProperty, formatGscPropertyCandidates, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingEligibility, getIndexingMetadata, getLatestGscDate, getNextCheckAfter, getNextCheckPriority, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, groupIntoRanges, gscErrorToException, gscPropertyMatchesTarget, hasGoogleScope, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, inspectUrlFlat, introspectAccessToken, introspectAccessTokenResult, isErr, isOk, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, listVerifiedSites, matchGscSite, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, ok, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, resolveVerificationTarget, rethrowAsGscApiError, revokeOAuthToken, revokeOAuthTokenResult, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, submitSitemap, toIsoDate, unmappedInspectionReasons, unverifySite, unwrapResult, urlMatchKey, verificationMethodsFor, verifySite };