gscdump 4.2.2 → 4.3.0

package/dist/core/errors.d.mts

@@ -1,4 +1,15 @@
 export type GscErrorKind = 'auth-expired' | 'permission-denied' | 'rate-limited' | 'not-found' | 'validation' | 'storage' | 'transport';
+/**
+ * Which Google quota a `rate-limited` refusal spent. Each one refills on its
+ * own clock, so a caller picks its backoff from this:
+ *
+ * - `load`: the Search Analytics load quota. Google charges it by query cost
+ *   (a `page,query,date` query on a large Site is the expensive shape) over
+ *   10 minute windows, so a retry sooner than that is refused again.
+ * - `daily`: a per-day cap. It resets at Pacific midnight.
+ * - `rate`: a per-second or per-minute cap. A short backoff clears it.
+ */
+export type GscQuota = 'load' | 'daily' | 'rate';
 export type GscError = {
   kind: 'auth-expired';
   message: string;
@@ -9,6 +20,7 @@ export type GscError = {
   cause: unknown;
 } | {
   kind: 'rate-limited';
+  quota: GscQuota;
   message: string;
   retryAfter?: number;
   cause: unknown;

package/dist/core/errors.mjs

@@ -59,7 +59,14 @@ function extractRetryAfter(error) {
 		return Number.isNaN(seconds) ? void 0 : seconds;
 	}
 }
-const QUOTA_MESSAGE_RE = /quota|rate\s*limit|\bqps\b/i;
+const QUOTA_MESSAGE_RE = /quota|rate\s*limit|\bqps\b|daily\s*limit/i;
+const LOAD_QUOTA_MESSAGE_RE = /load\s*quota/i;
+const DAILY_QUOTA_MESSAGE_RE = /daily\s*limit|per\s*day|for\s*the\s*day/i;
+const DAILY_QUOTA_REASONS = /* @__PURE__ */ new Set([
+	"dailyLimitExceeded",
+	"dailyLimitExceededUnreg",
+	"variableTermExpiredDailyExceeded"
+]);
 const QUOTA_REASONS = /* @__PURE__ */ new Set([
 	"dailyLimitExceeded",
 	"dailyLimitExceededUnreg",
@@ -98,6 +105,12 @@ function isQuotaCondition(cause, message) {
 	if (reason && QUOTA_REASONS.has(reason)) return true;
 	return QUOTA_MESSAGE_RE.test(message);
 }
+function quotaOf(cause, message) {
+	if (LOAD_QUOTA_MESSAGE_RE.test(message)) return "load";
+	const reason = extractReason(cause);
+	if (reason && DAILY_QUOTA_REASONS.has(reason) || DAILY_QUOTA_MESSAGE_RE.test(message)) return "daily";
+	return "rate";
+}
 function classifyError(cause) {
 	const status = extractStatus(cause);
 	const message = extractMessage(cause);
@@ -108,6 +121,7 @@ function classifyError(cause) {
 	};
 	if (status === 429) return {
 		kind: "rate-limited",
+		quota: quotaOf(cause, message),
 		message,
 		retryAfter: extractRetryAfter(cause),
 		cause
@@ -115,6 +129,7 @@ function classifyError(cause) {
 	if (status === 403) {
 		if (isQuotaCondition(cause, message)) return {
 			kind: "rate-limited",
+			quota: quotaOf(cause, message),
 			message,
 			retryAfter: extractRetryAfter(cause),
 			cause

package/dist/errors.d.mts

@@ -1,2 +1,2 @@
-import { GscApiError, GscApiErrorInfo, GscError, GscErrorKind, classifyError, gscErrorToException, isPermissionDeniedError, parseGoogleError, rethrowAsGscApiError } from "./core/errors.mjs";
-export { GscApiError, type GscApiErrorInfo, type GscError, type GscErrorKind, classifyError, gscErrorToException, isPermissionDeniedError, parseGoogleError, rethrowAsGscApiError };
+import { GscApiError, GscApiErrorInfo, GscError, GscErrorKind, GscQuota, classifyError, gscErrorToException, isPermissionDeniedError, parseGoogleError, rethrowAsGscApiError } from "./core/errors.mjs";
+export { GscApiError, type GscApiErrorInfo, type GscError, type GscErrorKind, type GscQuota, classifyError, gscErrorToException, isPermissionDeniedError, parseGoogleError, rethrowAsGscApiError };

package/dist/index.d.mts

@@ -4,7 +4,7 @@ import { Auth, AuthClient, AuthOptions, CallOptions, DEFAULT_GSC_REQUEST_TIMEOUT
 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 { 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 { GscApiError, GscApiErrorInfo, GscError, GscErrorKind, classifyError, gscErrorToException, isPermissionDeniedError, parseGoogleError, rethrowAsGscApiError } from "./core/errors.mjs";
+import { GscApiError, GscApiErrorInfo, GscError, GscErrorKind, GscQuota, classifyError, gscErrorToException, isPermissionDeniedError, parseGoogleError, rethrowAsGscApiError } from "./core/errors.mjs";
 import { runSequentialBatch } from "./api/batch.mjs";
 import { IndexingMetadata, IndexingNotificationType, IndexingResult, batchRequestIndexing, getIndexingMetadata, requestIndexing } from "./api/indexing.mjs";
 import { BatchInspectUrlsFlatSettledOptions, IndexingEligibility, IndexingIneligibleReason, InspectUrlFlatSettledResult, InspectUrlResult, InspectionPriority, LegacyInspectionPriority, MAX_FLAT_INSPECTION_BATCH_CONCURRENCY, ParsedIndexingResult, URL_INSPECTION_QUOTA, ValueWeightedInspectionPriority, batchInspectUrls, batchInspectUrlsFlatSettled, canUseUrlInspection, describeInspectionError, getIndexingEligibility, getNextCheckAfter, getNextCheckPriority, inspectUrl, inspectUrlFlat } from "./api/inspection.mjs";
@@ -20,4 +20,4 @@ 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 { decodeSiteId, encodeSiteId, normalizeSiteUrl } from "./tenant.mjs";
 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, CanonicalDifferenceKind, DAYS_PER_RANGE, DEFAULT_GSC_REQUEST_TIMEOUT_MS, DataRow, DimensionFilter, DimensionFilterGroup, Err, 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, LegacyInspectionPriority, 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, SiteCandidate, SiteResolution, type SitemapNextAction, type SitemapStatus, URL_INSPECTION_EFFECTIVE_LIMIT, URL_INSPECTION_QUOTA, UnmappedInspectionReasons, UrlInspectionResult, UrlNotification, UrlNotificationMetadata, ValueWeightedInspectionPriority, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchInspectUrlsFlatSettled, batchRequestIndexing, canUseUrlInspection, classifyCanonicalDifference, classifyError, countDays, createAuth, createFetch, decodeSiteId, deleteSite, deleteSitemap, describeInspectionError, encodeSiteId, err, exchangeAuthCodeResult, fetchSitemap, 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, isCanonicalMismatch, isErr, isFragmentUrl, isOk, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, listVerifiedSites, matchGscSite, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, ok, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, resolveSiteInput, resolveVerificationTarget, rethrowAsGscApiError, revokeOAuthToken, revokeOAuthTokenResult, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, submitSitemap, toIsoDate, unmappedInspectionReasons, unverifySite, unwrapResult, urlMatchKey, verificationMethodsFor, verifySite };
+export { type AccountNextAction, type AccountStatus, AmpInspectionResult, AmpIssue, type AnalyticsNextAction, type AnalyticsStatus, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, type BackfillProgress, BatchInspectUrlsFlatSettledOptions, CallOptions, CanonicalDifferenceKind, DAYS_PER_RANGE, DEFAULT_GSC_REQUEST_TIMEOUT_MS, DataRow, DimensionFilter, DimensionFilterGroup, Err, 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, type GscQuota, 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, LegacyInspectionPriority, 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, SiteCandidate, SiteResolution, type SitemapNextAction, type SitemapStatus, URL_INSPECTION_EFFECTIVE_LIMIT, URL_INSPECTION_QUOTA, UnmappedInspectionReasons, UrlInspectionResult, UrlNotification, UrlNotificationMetadata, ValueWeightedInspectionPriority, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchInspectUrlsFlatSettled, batchRequestIndexing, canUseUrlInspection, classifyCanonicalDifference, classifyError, countDays, createAuth, createFetch, decodeSiteId, deleteSite, deleteSitemap, describeInspectionError, encodeSiteId, err, exchangeAuthCodeResult, fetchSitemap, 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, isCanonicalMismatch, isErr, isFragmentUrl, isOk, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, listVerifiedSites, matchGscSite, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, ok, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, resolveSiteInput, resolveVerificationTarget, rethrowAsGscApiError, revokeOAuthToken, revokeOAuthTokenResult, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, submitSitemap, toIsoDate, unmappedInspectionReasons, unverifySite, unwrapResult, urlMatchKey, verificationMethodsFor, verifySite };

package/dist/query/types.d.mts

@@ -57,7 +57,7 @@ export interface MetricColumn<M extends Metric> {
   readonly __metricColumnBrand: 'gscdump.MetricColumn';
   readonly metric: M;
 }
-export interface BuilderState {
+export type BuilderState = {
   dimensions: Dimension[];
   metrics?: Metric[];
   filter?: Filter<any>;
@@ -74,7 +74,7 @@ export interface BuilderState {
   aggregationType?: GscAggregationType;
   /** GSC search corpus. Wins over any `searchType` filter when both are set. */
   searchType?: SearchType;
-}
+};
 export interface JsonInternalFilter {
   dimension: string;
   operator: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gscdump",
   "type": "module",
-  "version": "4.2.2",
+  "version": "4.3.0",
   "description": "Direct Google Search Console and Bing Webmaster clients with typed queries and Indexing Evidence",
   "author": {
     "name": "Harlan Wilton",
@@ -113,7 +113,7 @@
     "node": ">=22.13.0"
   },
   "dependencies": {
-    "@gscdump/contracts": "^4.2.2",
+    "@gscdump/contracts": "^4.3.0",
     "ofetch": "^1.5.1"
   },
   "scripts": {