gscdump 0.25.13 → 0.26.0

package/dist/core/result.d.mts

@@ -0,0 +1,29 @@
+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>;
+declare function ok<A>(value: A): Ok<A>;
+declare function err<E>(error: E): Err<E>;
+declare function isOk<A, E>(result: Result<A, E>): result is Ok<A>;
+declare function isErr<A, E>(result: Result<A, E>): result is Err<E>;
+/** Maps the success channel, leaving an `Err` untouched. */
+declare function mapResult<A, B, E>(result: Result<A, E>, f: (value: A) => B): Result<B, E>;
+/** Maps the error channel, leaving an `Ok` untouched. */
+declare function mapErr<A, E, F>(result: Result<A, E>, f: (error: E) => F): Result<A, F>;
+/** Folds both channels into a single value. */
+declare function matchResult<A, E, R>(result: Result<A, E>, handlers: {
+  onOk: (value: A) => R;
+  onErr: (error: E) => R;
+}): R;
+/**
+ * Collapses a `Result` back into the throwing world: returns the value or throws
+ * via `toError`. Used by the throwing wrappers that sit over the `Result` core so
+ * existing call sites keep their `await`/`throw` ergonomics.
+ */
+declare function unwrapResult<A, E>(result: Result<A, E>, toError: (error: E) => unknown): A;
+export { Err, Ok, Result, err, isErr, isOk, mapErr, mapResult, matchResult, ok, unwrapResult };

package/dist/core/result.mjs

@@ -0,0 +1,32 @@
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function err(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+function isOk(result) {
+	return result.ok;
+}
+function isErr(result) {
+	return !result.ok;
+}
+function mapResult(result, f) {
+	return result.ok ? ok(f(result.value)) : result;
+}
+function mapErr(result, f) {
+	return result.ok ? result : err(f(result.error));
+}
+function matchResult(result, handlers) {
+	return result.ok ? handlers.onOk(result.value) : handlers.onErr(result.error);
+}
+function unwrapResult(result, toError) {
+	if (result.ok) return result.value;
+	throw toError(result.error);
+}
+export { err, isErr, isOk, mapErr, mapResult, matchResult, ok, unwrapResult };

package/dist/index.d.mts

@@ -423,17 +423,134 @@ interface IndexingEligibility {
   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;
+};
+/** 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 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>;
+declare function ok<A>(value: A): Ok<A>;
+declare function err<E>(error: E): Err<E>;
+declare function isOk<A, E>(result: Result<A, E>): result is Ok<A>;
+declare function isErr<A, E>(result: Result<A, E>): result is Err<E>;
+/** Maps the success channel, leaving an `Err` untouched. */
+declare function mapResult<A, B, E>(result: Result<A, E>, f: (value: A) => B): Result<B, E>;
+/** Maps the error channel, leaving an `Ok` untouched. */
+declare function mapErr<A, E, F>(result: Result<A, E>, f: (error: E) => F): Result<A, F>;
+/** Folds both channels into a single value. */
+declare function matchResult<A, E, R>(result: Result<A, E>, handlers: {
+  onOk: (value: A) => R;
+  onErr: (error: E) => R;
+}): R;
+/**
+ * Collapses a `Result` back into the throwing world: returns the value or throws
+ * via `toError`. Used by the throwing wrappers that sit over the `Result` core so
+ * existing call sites keep their `await`/`throw` ergonomics.
+ */
+declare function unwrapResult<A, E>(result: Result<A, E>, toError: (error: E) => unknown): A;
 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`.
@@ -539,74 +656,6 @@ declare function rowWithMetricDefaults(row: {
   position: number;
 };
 declare function progressBar(current: number, total: number, label: string, width?: number): string;
-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;
-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;
 /** Milliseconds in a UTC day. Use for date arithmetic without DST surprises. */
 declare const MS_PER_DAY = 86400000;
 /** Format a Date as YYYY-MM-DD (UTC). */
@@ -919,4 +968,4 @@ declare function normalizeSiteUrl(siteUrl: string): string;
  * Example: `https://www.Example.com/Foo/` → `example.com/foo`
  */
 declare function urlMatchKey(url: string): string | null;
-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_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, QueryReturn, QuerySourceMode, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, SitemapNextAction, SitemapStatus, URL_INSPECTION_DAILY_LIMIT, URL_INSPECTION_EFFECTIVE_LIMIT, UrlInspectionResult, UrlNotificationMetadata, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchRequestIndexing, canUseUrlInspection, classifyError, countDays, createAuth, createFetch, daysAgo, decodeSiteId, deleteSite, deleteSitemap, discoverSitemap, encodeSiteId, 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, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, progressBar, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, rethrowAsGscApiError, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unverifySite, urlMatchKey, verificationMethodsFor, verifySite };
+export { AccountNextAction, AccountStatus, AnalyticsNextAction, AnalyticsStatus, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, BackfillProgress, CallOptions, DAYS_PER_RANGE, DataRow, DimensionFilter, DimensionFilterGroup, DiscoverSitemapOptions, Err, 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_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, Ok, ParsedGscSiteUrl, ParsedIndexingResult, PartnerLifecycleAccount, PartnerLifecycleResponse, PartnerLifecycleSite, Period, PropertyNextAction, PropertyStatus, PublishUrlNotificationResponse, QueryReturn, QuerySourceMode, RequiredNonNullable, ResolvedAnalyticsRange, Result, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, SitemapNextAction, SitemapStatus, URL_INSPECTION_DAILY_LIMIT, URL_INSPECTION_EFFECTIVE_LIMIT, UrlInspectionResult, UrlNotificationMetadata, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchRequestIndexing, canUseUrlInspection, classifyError, countDays, createAuth, createFetch, daysAgo, decodeSiteId, deleteSite, deleteSitemap, discoverSitemap, encodeSiteId, err, exchangeAuthCode, exchangeAuthCodeResult, 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, gscErrorToException, gscPropertyMatchesTarget, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, inspectUrlFlat, isErr, isOk, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, lifecycleWebhookEvents, listVerifiedSites, mapErr, mapResult, matchGscSite, matchResult, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, ok, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, progressBar, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, refreshAccessTokenResult, requestIndexing, rethrowAsGscApiError, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unverifySite, unwrapResult, urlMatchKey, verificationMethodsFor, verifySite };

package/dist/index.mjs

@@ -327,6 +327,12 @@ function storageError(message, cause) {
 		cause
 	};
 }
+function gscErrorToException(error) {
+	const exception = new Error(error.message);
+	if (error.cause !== void 0) exception.cause = error.cause;
+	exception.gscError = error;
+	return exception;
+}
 function parseGoogleError(text, httpStatus) {
 	let parsed = null;
 	try {
@@ -409,6 +415,37 @@ function formatErrorForCli(cause) {
 	}
 	return lines.join("\n");
 }
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function err(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+function isOk(result) {
+	return result.ok;
+}
+function isErr(result) {
+	return !result.ok;
+}
+function mapResult(result, f) {
+	return result.ok ? ok(f(result.value)) : result;
+}
+function mapErr(result, f) {
+	return result.ok ? result : err(f(result.error));
+}
+function matchResult(result, handlers) {
+	return result.ok ? handlers.onOk(result.value) : handlers.onErr(result.error);
+}
+function unwrapResult(result, toError) {
+	if (result.ok) return result.value;
+	throw toError(result.error);
+}
 const OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
 const OAUTH_TIMEOUT_MS = 8e3;
 const OAUTH_MAX_ATTEMPTS = 3;
@@ -417,29 +454,53 @@ const OAUTH_BACKOFF_MS = [
 	400,
 	1500
 ];
-async function refreshAccessToken(refreshToken, clientId, clientSecret) {
-	return postOAuthToken(new URLSearchParams({
+async function refreshAccessTokenResult(refreshToken, clientId, clientSecret) {
+	return postOAuthTokenResult(new URLSearchParams({
 		client_id: clientId,
 		client_secret: clientSecret,
 		refresh_token: refreshToken,
 		grant_type: "refresh_token"
 	}), "refresh");
 }
-async function exchangeAuthCode(code, clientId, clientSecret, redirectUri) {
-	const tokens = await postOAuthToken(new URLSearchParams({
+async function refreshAccessToken(refreshToken, clientId, clientSecret) {
+	return unwrapResult(await refreshAccessTokenResult(refreshToken, clientId, clientSecret), oauthErrorToException);
+}
+async function exchangeAuthCodeResult(code, clientId, clientSecret, redirectUri) {
+	const result = await postOAuthTokenResult(new URLSearchParams({
 		client_id: clientId,
 		client_secret: clientSecret,
 		code,
 		redirect_uri: redirectUri,
 		grant_type: "authorization_code"
 	}), "exchange");
-	const refreshToken = tokens.refresh_token;
-	return {
-		...tokens,
+	if (!result.ok) return result;
+	const refreshToken = result.value.refresh_token;
+	return ok({
+		...result.value,
 		refreshToken
+	});
+}
+async function exchangeAuthCode(code, clientId, clientSecret, redirectUri) {
+	return unwrapResult(await exchangeAuthCodeResult(code, clientId, clientSecret, redirectUri), oauthErrorToException);
+}
+function oauthHttpError(op, info) {
+	const message = `Failed to ${op} token: ${info.message}`;
+	const cause = new GscApiError(message, info);
+	return info.reason === "invalid_grant" || info.code === 400 || info.code === 401 || info.code === 403 ? {
+		kind: "auth-expired",
+		message,
+		cause
+	} : {
+		kind: "transport",
+		message,
+		status: info.code,
+		cause
 	};
 }
-async function postOAuthToken(body, op) {
+function oauthErrorToException(error) {
+	return error.cause instanceof Error ? error.cause : gscErrorToException(error);
+}
+async function postOAuthTokenResult(body, op) {
 	let lastError;
 	for (let attempt = 0; attempt < OAUTH_MAX_ATTEMPTS; attempt++) {
 		if (OAUTH_BACKOFF_MS[attempt]) await new Promise((r) => setTimeout(r, OAUTH_BACKOFF_MS[attempt]));
@@ -448,23 +509,24 @@ async function postOAuthToken(body, op) {
 			headers: { "Content-Type": "application/x-www-form-urlencoded" },
 			body,
 			signal: AbortSignal.timeout(OAUTH_TIMEOUT_MS)
-		}).catch((err) => {
-			lastError = err;
+		}).catch((error) => {
+			lastError = error;
 			return null;
 		});
 		if (!res) continue;
-		if (!res.ok) {
-			const info = parseGoogleError(await res.text(), res.status);
-			throw new GscApiError(`Failed to ${op} token: ${info.message}`, info);
-		}
+		if (!res.ok) return err(oauthHttpError(op, parseGoogleError(await res.text(), res.status)));
 		const data = await res.json();
-		return {
+		return ok({
 			accessToken: data.access_token,
 			expiresAt: Math.floor(Date.now() / 1e3) + data.expires_in,
 			refresh_token: data.refresh_token
-		};
+		});
 	}
-	throw lastError instanceof Error ? lastError : /* @__PURE__ */ new Error(`OAuth ${op} failed after ${OAUTH_MAX_ATTEMPTS} attempts`);
+	return err({
+		kind: "transport",
+		message: lastError instanceof Error ? lastError.message : `OAuth ${op} failed after ${OAUTH_MAX_ATTEMPTS} attempts`,
+		cause: lastError
+	});
 }
 async function fetchSites(client) {
 	return client.sites();
@@ -2152,6 +2214,126 @@ const SearchTypes = {
 	GOOGLE_NEWS: "googleNews"
 };
 Object.fromEntries(countries_default.map((c) => [c["alpha-3"], c["alpha-3"].toLowerCase()]));
+const TIME_AXIS_DIMENSIONS = new Set(["date", "hour"]);
+const queryErrors = {
+	missingDateRange() {
+		return {
+			kind: "missing-date-range",
+			message: "Date range required: use .where(between(date, start, end)) or .where(and(gte(date, start), lte(date, end)))"
+		};
+	},
+	invalidRowLimit(value) {
+		return {
+			kind: "invalid-row-limit",
+			value,
+			message: `rowLimit must be a positive integer, got ${value}`
+		};
+	},
+	invalidStartRow(value) {
+		return {
+			kind: "invalid-start-row",
+			value,
+			message: `startRow must be a non-negative integer, got ${value}`
+		};
+	},
+	hourDimensionRequiresHourlyState() {
+		return {
+			kind: "invalid-data-state",
+			message: "hour dimension requires dataState: \"hourly_all\""
+		};
+	},
+	hourlyStateRequiresHourDimension() {
+		return {
+			kind: "invalid-data-state",
+			message: "dataState: \"hourly_all\" requires grouping by hour dimension"
+		};
+	},
+	byPropertyUnsupportedSearchType() {
+		return {
+			kind: "invalid-aggregation-type",
+			message: "aggregationType: \"byProperty\" is not supported for type \"discover\" or \"googleNews\""
+		};
+	},
+	byPropertyNotAllowedWithPage() {
+		return {
+			kind: "invalid-aggregation-type",
+			message: "aggregationType: \"byProperty\" is not allowed when grouping or filtering by page"
+		};
+	},
+	byNewsShowcaseRequiresSearchType() {
+		return {
+			kind: "invalid-aggregation-type",
+			message: "aggregationType: \"byNewsShowcasePanel\" requires type \"discover\" or \"googleNews\""
+		};
+	},
+	byNewsShowcaseNotAllowedWithPage() {
+		return {
+			kind: "invalid-aggregation-type",
+			message: "aggregationType: \"byNewsShowcasePanel\" is not allowed when grouping or filtering by page"
+		};
+	},
+	byNewsShowcaseRequiresShowcaseFilter() {
+		return {
+			kind: "invalid-aggregation-type",
+			message: "aggregationType: \"byNewsShowcasePanel\" requires a searchAppearance equals \"NEWS_SHOWCASE\" filter and no other searchAppearance filter"
+		};
+	},
+	invalidBuilderState(cause) {
+		return {
+			kind: "invalid-builder-state",
+			cause,
+			message: "Invalid state"
+		};
+	},
+	unsupportedCapability(capability, context) {
+		return {
+			kind: "unsupported-capability",
+			capability,
+			context,
+			message: `${context} requires ${capability} capability`
+		};
+	},
+	unresolvableDataset(dimensions, filterDims = []) {
+		const grouped = dimensions.filter((d) => !TIME_AXIS_DIMENSIONS.has(d));
+		const filtered = filterDims.filter((d) => !TIME_AXIS_DIMENSIONS.has(d));
+		return {
+			kind: "unresolvable-dataset",
+			dimensions,
+			filterDims,
+			message: `Cannot resolve a [${grouped.join(", ")}] breakdown filtered by [${filtered.join(", ")}] from stored data: these dimensions live in separate per-dimension tables. Only the live GSC API computes cross-dimension aggregates.`
+		};
+	}
+};
+var UnsupportedLogicalCapabilityError = class extends Error {
+	queryError;
+	constructor(capability, context) {
+		const error = queryErrors.unsupportedCapability(capability, context);
+		super(error.message);
+		this.name = "UnsupportedLogicalCapabilityError";
+		this.queryError = error;
+	}
+};
+var UnresolvableDatasetError = class extends Error {
+	queryError;
+	constructor(dimensions, filterDims = []) {
+		const error = queryErrors.unresolvableDataset(dimensions, filterDims);
+		super(error.message);
+		this.name = "UnresolvableDatasetError";
+		this.queryError = error;
+	}
+};
+function queryErrorToException(error) {
+	switch (error.kind) {
+		case "unsupported-capability": return new UnsupportedLogicalCapabilityError(error.capability, error.context);
+		case "unresolvable-dataset": return new UnresolvableDatasetError(error.dimensions, error.filterDims);
+		default: {
+			const exception = new Error(error.message);
+			if ("cause" in error && error.cause !== void 0) exception.cause = error.cause;
+			exception.queryError = error;
+			return exception;
+		}
+	}
+}
 const DATE_OPERATORS = [
 	"gte",
 	"gt",
@@ -2229,9 +2411,9 @@ function extractSpecialFilters(filter) {
 		dimensionFilter
 	};
 }
-function resolveToBody(state) {
+function resolveToBodyResult(state) {
 	const { startDate, endDate, searchType, dimensionFilter } = extractSpecialFilters(state.filter);
-	if (!startDate || !endDate) throw new Error("Date range required: use .where(between(date, start, end)) or .where(and(gte(date, start), lte(date, end)))");
+	if (!startDate || !endDate) return err(queryErrors.missingDateRange());
 	const body = {
 		dimensions: state.dimensions,
 		startDate,
@@ -2240,16 +2422,16 @@ function resolveToBody(state) {
 	const resolvedType = state.searchType ?? searchType;
 	if (resolvedType) body.type = resolvedType;
 	if (state.rowLimit !== void 0) {
-		if (!Number.isInteger(state.rowLimit) || state.rowLimit < 1) throw new Error(`rowLimit must be a positive integer, got ${state.rowLimit}`);
+		if (!Number.isInteger(state.rowLimit) || state.rowLimit < 1) return err(queryErrors.invalidRowLimit(state.rowLimit));
 		body.rowLimit = state.rowLimit;
 	}
 	if (state.startRow !== void 0) {
-		if (!Number.isInteger(state.startRow) || state.startRow < 0) throw new Error(`startRow must be a non-negative integer, got ${state.startRow}`);
+		if (!Number.isInteger(state.startRow) || state.startRow < 0) return err(queryErrors.invalidStartRow(state.startRow));
 		if (state.startRow > 0) body.startRow = state.startRow;
 	}
 	const hasHour = state.dimensions?.includes("hour");
-	if (hasHour && state.dataState !== "hourly_all") throw new Error("hour dimension requires dataState: \"hourly_all\"");
-	if (state.dataState === "hourly_all" && !hasHour) throw new Error("dataState: \"hourly_all\" requires grouping by hour dimension");
+	if (hasHour && state.dataState !== "hourly_all") return err(queryErrors.hourDimensionRequiresHourlyState());
+	if (state.dataState === "hourly_all" && !hasHour) return err(queryErrors.hourlyStateRequiresHourDimension());
 	if (state.dataState) body.dataState = state.dataState;
 	const filterGroups = resolveFilter(dimensionFilter);
 	if (filterGroups.length > 0) body.dimensionFilterGroups = filterGroups;
@@ -2258,20 +2440,23 @@ function resolveToBody(state) {
 		const apiLeafFilters = filterGroups.flatMap((g) => g.filters ?? []);
 		const filtersByPage = apiLeafFilters.some((f) => f.dimension === "page");
 		if (state.aggregationType === "byProperty") {
-			if (body.type === "discover" || body.type === "googleNews") throw new Error("aggregationType: \"byProperty\" is not supported for type \"discover\" or \"googleNews\"");
-			if (groupsByPage || filtersByPage) throw new Error("aggregationType: \"byProperty\" is not allowed when grouping or filtering by page");
+			if (body.type === "discover" || body.type === "googleNews") return err(queryErrors.byPropertyUnsupportedSearchType());
+			if (groupsByPage || filtersByPage) return err(queryErrors.byPropertyNotAllowedWithPage());
 		}
 		if (state.aggregationType === "byNewsShowcasePanel") {
-			if (body.type !== "discover" && body.type !== "googleNews") throw new Error("aggregationType: \"byNewsShowcasePanel\" requires type \"discover\" or \"googleNews\"");
-			if (groupsByPage || filtersByPage) throw new Error("aggregationType: \"byNewsShowcasePanel\" is not allowed when grouping or filtering by page");
+			if (body.type !== "discover" && body.type !== "googleNews") return err(queryErrors.byNewsShowcaseRequiresSearchType());
+			if (groupsByPage || filtersByPage) return err(queryErrors.byNewsShowcaseNotAllowedWithPage());
 			const saFilters = apiLeafFilters.filter((f) => f.dimension === "searchAppearance");
 			const hasNewsShowcase = saFilters.some((f) => f.operator === "equals" && f.expression === "NEWS_SHOWCASE");
 			const hasOther = saFilters.some((f) => !(f.operator === "equals" && f.expression === "NEWS_SHOWCASE"));
-			if (!hasNewsShowcase || hasOther) throw new Error("aggregationType: \"byNewsShowcasePanel\" requires a searchAppearance equals \"NEWS_SHOWCASE\" filter and no other searchAppearance filter");
+			if (!hasNewsShowcase || hasOther) return err(queryErrors.byNewsShowcaseRequiresShowcaseFilter());
 		}
 		body.aggregationType = state.aggregationType;
 	}
-	return body;
+	return ok(body);
+}
+function resolveToBody(state) {
+	return unwrapResult(resolveToBodyResult(state), queryErrorToException);
 }
 function isApiFilter(f) {
 	return !isMetricOperator(f.operator) && !isSpecialOperator(f.operator);
@@ -3072,4 +3257,4 @@ function urlMatchKey(url) {
 	if (!u) return null;
 	return [u.hostname.replace(/^www\./, ""), u.pathname.replace(/\/$/, "") || "/"].join("").toLowerCase();
 }
-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_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, MS_PER_DAY, URL_INSPECTION_DAILY_LIMIT, URL_INSPECTION_EFFECTIVE_LIMIT, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchRequestIndexing, canUseUrlInspection, classifyError, countDays, createAuth, createFetch, daysAgo, decodeSiteId, deleteSite, deleteSitemap, discoverSitemap, encodeSiteId, 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, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, progressBar, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, rethrowAsGscApiError, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unverifySite, urlMatchKey, 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_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, MS_PER_DAY, URL_INSPECTION_DAILY_LIMIT, URL_INSPECTION_EFFECTIVE_LIMIT, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchRequestIndexing, canUseUrlInspection, classifyError, countDays, createAuth, createFetch, daysAgo, decodeSiteId, deleteSite, deleteSitemap, discoverSitemap, encodeSiteId, err, exchangeAuthCode, exchangeAuthCodeResult, 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, gscErrorToException, gscPropertyMatchesTarget, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, inspectUrlFlat, isErr, isOk, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, lifecycleWebhookEvents, listVerifiedSites, mapErr, mapResult, matchGscSite, matchResult, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, ok, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, progressBar, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, refreshAccessTokenResult, requestIndexing, rethrowAsGscApiError, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unverifySite, unwrapResult, urlMatchKey, verificationMethodsFor, verifySite };