gscdump 0.17.1 → 0.17.2

package/dist/index.d.mts

@@ -346,6 +346,40 @@ declare function batchInspectUrls(client: GoogleSearchConsoleClient, siteUrl: st
   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;
+  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 OAuthTokens {
   accessToken: string;
   /** Unix seconds. */
@@ -808,4 +842,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, 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 };
+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, IndexingEligibility, IndexingIneligibleReason, IndexingIssueType, IndexingMetadata, IndexingNextAction, IndexingNotificationType, IndexingResult, IndexingStatus, InspectUrlIndexResponse, InspectUrlResult, InspectionPriority, LifecycleError, LifecycleErrorCode, LifecycleProgress, LifecycleWebhookEnvelope, LifecycleWebhookEvent, MS_PER_DAY, MobileUsabilityResult, OAuthTokens, ParsedGscSiteUrl, ParsedIndexingResult, 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, canUseUrlInspection, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSite, deleteSitemap, discoverSitemap, exchangeAuthCode, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, findBestGscProperty, findExactGscProperty, formatErrorForCli, formatGscPropertyCandidates, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingEligibility, getIndexingMetadata, getLatestGscDate, getNextCheckAfter, getNextCheckPriority, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, grantedScopeList, groupIntoRanges, gscPropertyMatchesTarget, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, inspectUrlFlat, 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 };

package/dist/index.mjs

@@ -50,6 +50,18 @@ async function batchRequestIndexing(client, urls, options = {}) {
 		onProgress
 	});
 }
+function hasGscReadScope(scopes) {
+	if (!scopes) return false;
+	return scopes.includes("webmasters.readonly") || scopes.includes("webmasters");
+}
+function hasGscWriteScope(scopes) {
+	if (!scopes) return false;
+	return scopes.includes("webmasters") && !scopes.includes("webmasters.readonly");
+}
+function hasIndexingScope(scopes) {
+	if (!scopes) return false;
+	return scopes.includes("googleapis.com/auth/indexing");
+}
 async function inspectUrl(client, siteUrl, inspectionUrl) {
 	const inspection = (await client.inspect(siteUrl, inspectionUrl)).inspectionResult;
 	return {
@@ -72,6 +84,72 @@ async function batchInspectUrls(client, siteUrl, urls, options = {}) {
 		onProgress
 	});
 }
+async function inspectUrlFlat(client, siteUrl, inspectionUrl) {
+	const inspection = (await client.inspect(siteUrl, inspectionUrl)).inspectionResult;
+	const index = inspection?.indexStatusResult;
+	const mobile = inspection?.mobileUsabilityResult;
+	const rich = inspection?.richResultsResult;
+	return {
+		url: inspectionUrl,
+		verdict: index?.verdict ?? null,
+		coverageState: index?.coverageState ?? null,
+		indexingState: index?.indexingState ?? null,
+		robotsTxtState: index?.robotsTxtState ?? null,
+		pageFetchState: index?.pageFetchState ?? null,
+		lastCrawlTime: index?.lastCrawlTime ?? null,
+		crawlingUserAgent: index?.crawledAs ?? null,
+		userCanonical: index?.userCanonical ?? null,
+		googleCanonical: index?.googleCanonical ?? null,
+		sitemaps: index?.sitemap?.length ? JSON.stringify(index.sitemap) : null,
+		referringUrls: index?.referringUrls?.length ? JSON.stringify(index.referringUrls) : null,
+		mobileVerdict: mobile?.verdict ?? null,
+		mobileIssues: mobile?.issues?.length ? JSON.stringify(mobile.issues) : null,
+		richResultsVerdict: rich?.verdict ?? null,
+		richResultsItems: rich?.detectedItems?.length ? JSON.stringify(rich.detectedItems) : null,
+		inspectionResultLink: inspection?.inspectionResultLink ?? null
+	};
+}
+function getNextCheckPriority(result) {
+	if (!result.verdict || result.verdict === "VERDICT_UNSPECIFIED") return "medium";
+	if (result.verdict === "FAIL" || result.verdict === "PARTIAL" || result.verdict === "NEUTRAL") return "high";
+	if (result.verdict === "PASS") return "low";
+	return "medium";
+}
+function getNextCheckAfter(priority) {
+	const now = Math.floor(Date.now() / 1e3);
+	switch (priority) {
+		case "high": return now + 7 * 86400;
+		case "medium": return now + 14 * 86400;
+		case "low": return now + 30 * 86400;
+	}
+}
+const INSPECTION_ALLOWED_PERMISSIONS = new Set(["siteOwner", "siteFullUser"]);
+function canUseUrlInspection(permissionLevel) {
+	return !!permissionLevel && INSPECTION_ALLOWED_PERMISSIONS.has(permissionLevel);
+}
+function grantedScopeList(scopes) {
+	return scopes?.split(/\s+/).map((s) => s.trim()).filter(Boolean) ?? [];
+}
+function getIndexingEligibility(grantedScopes, permissionLevel) {
+	const scopes = grantedScopeList(grantedScopes);
+	if (!hasIndexingScope(grantedScopes)) return {
+		indexingEligible: false,
+		indexingIneligibleReason: "missing_indexing_scope",
+		indexingPermissionLevel: permissionLevel ?? null,
+		grantedScopes: scopes
+	};
+	if (!canUseUrlInspection(permissionLevel)) return {
+		indexingEligible: false,
+		indexingIneligibleReason: "insufficient_gsc_permission",
+		indexingPermissionLevel: permissionLevel ?? null,
+		grantedScopes: scopes
+	};
+	return {
+		indexingEligible: true,
+		indexingPermissionLevel: permissionLevel ?? null,
+		grantedScopes: scopes
+	};
+}
 const GSC_QUOTAS = {
 	searchAnalytics: 25e3,
 	urlInspection: 2e3,
@@ -2619,18 +2697,6 @@ function formatGscPropertyCandidates(candidates) {
 }
 const INDEXING_DAILY_LIMIT = 2e3;
 const INDEXING_EFFECTIVE_LIMIT = 1800;
-function hasGscReadScope(scopes) {
-	if (!scopes) return false;
-	return scopes.includes("webmasters.readonly") || scopes.includes("webmasters");
-}
-function hasGscWriteScope(scopes) {
-	if (!scopes) return false;
-	return scopes.includes("webmasters") && !scopes.includes("webmasters.readonly");
-}
-function hasIndexingScope(scopes) {
-	if (!scopes) return false;
-	return scopes.includes("googleapis.com/auth/indexing");
-}
 const GSCDUMP_ONBOARDING_CONTRACT_VERSION = "2026-05-11";
 const GSCDUMP_REQUIRED_ANALYTICS_SCOPE = "https://www.googleapis.com/auth/webmasters.readonly";
 const GSCDUMP_OPTIONAL_INDEXING_SCOPE = "https://www.googleapis.com/auth/indexing";
@@ -2819,4 +2885,4 @@ async function fetchSitemapUrls(sitemapUrl, options = {}) {
 	await visit(sitemapUrl, 0);
 	return out;
 }
-export { DAYS_PER_RANGE, 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, GscApiError, INDEXING_DAILY_LIMIT, INDEXING_EFFECTIVE_LIMIT, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, MS_PER_DAY, 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 };
+export { DAYS_PER_RANGE, 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, GscApiError, INDEXING_DAILY_LIMIT, INDEXING_EFFECTIVE_LIMIT, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, MS_PER_DAY, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchRequestIndexing, canUseUrlInspection, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSite, deleteSitemap, discoverSitemap, exchangeAuthCode, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, findBestGscProperty, findExactGscProperty, formatErrorForCli, formatGscPropertyCandidates, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingEligibility, getIndexingMetadata, getLatestGscDate, getNextCheckAfter, getNextCheckPriority, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, grantedScopeList, groupIntoRanges, gscPropertyMatchesTarget, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, inspectUrlFlat, 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 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gscdump",
   "type": "module",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "description": "Google Search Console API wrapper with typed query builder, streaming pagination, and SEO analysis functions",
   "author": {
     "name": "Harlan Wilton",
@@ -108,7 +108,7 @@
     "defu": "^6.1.7",
     "ofetch": "^1.5.1",
     "ufo": "^1.6.4",
-    "@gscdump/contracts": "0.17.1"
+    "@gscdump/contracts": "0.17.2"
   },
   "devDependencies": {
     "@googleapis/indexing": "^6.0.1",