gscdump 0.17.0 → 0.17.1

package/dist/index.d.mts

@@ -346,6 +346,24 @@ declare function batchInspectUrls(client: GoogleSearchConsoleClient, siteUrl: st
   concurrency?: number;
   onProgress?: (result: InspectUrlResult, index: number, total: number) => void;
 }): Promise<InspectUrlResult[]>;
+interface OAuthTokens {
+  accessToken: string;
+  /** Unix seconds. */
+  expiresAt: number;
+}
+/**
+ * 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 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.
  */
@@ -485,6 +503,24 @@ declare const GSC_QUOTAS: {
 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;
+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).
@@ -580,11 +616,67 @@ declare const INDEXING_ISSUE_FILTERS: {
 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'>;
+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 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;
+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;
+/**
+ * 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;
 declare const GSCDUMP_ONBOARDING_CONTRACT_VERSION: "2026-05-11";
 declare const GSCDUMP_REQUIRED_ANALYTICS_SCOPE: "https://www.googleapis.com/auth/webmasters.readonly";
 declare const GSCDUMP_OPTIONAL_INDEXING_SCOPE: "https://www.googleapis.com/auth/indexing";
@@ -716,4 +808,4 @@ interface FetchSitemapUrlsOptions extends DiscoverSitemapOptions {
  * `<loc>https://...</loc>` shape but doesn't validate the schema.
  */
 declare function fetchSitemapUrls(sitemapUrl: string, options?: FetchSitemapUrlsOptions): Promise<string[]>;
-export { AccountNextAction, AccountStatus, AnalyticsNextAction, AnalyticsStatus, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, BackfillProgress, CallOptions, DAYS_PER_RANGE, DataRow, DimensionFilter, DimensionFilterGroup, DiscoverSitemapOptions, FetchSitemapUrlsOptions, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, 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, IndexingNextAction, IndexingNotificationType, IndexingResult, IndexingStatus, InspectUrlIndexResponse, InspectUrlResult, LifecycleError, LifecycleErrorCode, LifecycleProgress, LifecycleWebhookEnvelope, LifecycleWebhookEvent, MS_PER_DAY, MobileUsabilityResult, PartnerLifecycleAccount, PartnerLifecycleResponse, PartnerLifecycleSite, Period, PropertyNextAction, PropertyStatus, PublishUrlNotificationResponse, QuerySourceMode, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, SitemapNextAction, SitemapStatus, UrlInspectionResult, UrlNotificationMetadata, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchRequestIndexing, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSite, deleteSitemap, discoverSitemap, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingMetadata, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, groupIntoRanges, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, isPermissionDeniedError, isValidGscDate, lifecycleErrorCodes, lifecycleWebhookEvents, listVerifiedSites, parseGrantedScopes, progressBar, propertyNextActions, propertyStatuses, querySourceModes, requestIndexing, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unverifySite, verificationMethodsFor, verifySite };
+export { AccountNextAction, AccountStatus, AnalyticsNextAction, AnalyticsStatus, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, BackfillProgress, CallOptions, DAYS_PER_RANGE, DataRow, DimensionFilter, DimensionFilterGroup, DiscoverSitemapOptions, FetchSitemapUrlsOptions, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_QUOTAS, GSC_RETENTION_MONTHS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, GscApiError, GscApiErrorInfo, GscError, GscErrorKind, GscPropertyCandidate, GscdumpApiOptions, INDEXING_DAILY_LIMIT, INDEXING_EFFECTIVE_LIMIT, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, IndexStatusResult, IndexingIssueType, IndexingMetadata, IndexingNextAction, IndexingNotificationType, IndexingResult, IndexingStatus, InspectUrlIndexResponse, InspectUrlResult, LifecycleError, LifecycleErrorCode, LifecycleProgress, LifecycleWebhookEnvelope, LifecycleWebhookEvent, MS_PER_DAY, MobileUsabilityResult, OAuthTokens, ParsedGscSiteUrl, PartnerLifecycleAccount, PartnerLifecycleResponse, PartnerLifecycleSite, Period, PropertyNextAction, PropertyStatus, PublishUrlNotificationResponse, QuerySourceMode, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, SitemapNextAction, SitemapStatus, UrlInspectionResult, UrlNotificationMetadata, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchRequestIndexing, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSite, deleteSitemap, discoverSitemap, exchangeAuthCode, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, findBestGscProperty, findExactGscProperty, formatErrorForCli, formatGscPropertyCandidates, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingMetadata, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, groupIntoRanges, gscPropertyMatchesTarget, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, lifecycleWebhookEvents, listVerifiedSites, matchGscSite, normalizeRegistrationTarget, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, progressBar, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, rethrowAsGscApiError, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unverifySite, verificationMethodsFor, verifySite };