gscdump 1.4.0 → 1.4.2

package/dist/api/verification.mjs

@@ -0,0 +1,89 @@
+const SC_DOMAIN_PREFIX = "sc-domain:";
+function bareDomain(siteUrl) {
+	if (siteUrl.startsWith(SC_DOMAIN_PREFIX)) return siteUrl.slice(10);
+	try {
+		return new URL(siteUrl.startsWith("http") ? siteUrl : `https://${siteUrl}`).host;
+	} catch {
+		return siteUrl;
+	}
+}
+function urlPrefix(siteUrl) {
+	try {
+		const url = new URL(siteUrl.startsWith("http") ? siteUrl : `https://${siteUrl}`);
+		return `${url.protocol}//${url.host}/`;
+	} catch {
+		return siteUrl;
+	}
+}
+function siteUrlToVerificationSite(siteUrl) {
+	if (siteUrl.startsWith(SC_DOMAIN_PREFIX)) return {
+		type: "INET_DOMAIN",
+		identifier: siteUrl.slice(10)
+	};
+	return {
+		type: "SITE",
+		identifier: siteUrl
+	};
+}
+function resolveVerificationTarget(siteUrl, method) {
+	const isDomainProperty = siteUrl.startsWith(SC_DOMAIN_PREFIX);
+	const chosen = method ?? (isDomainProperty ? "DNS_TXT" : "META");
+	const isDns = chosen === "DNS_TXT" || chosen === "DNS_CNAME";
+	if (isDomainProperty && !isDns) return {
+		site: {
+			type: "INET_DOMAIN",
+			identifier: bareDomain(siteUrl)
+		},
+		method: "DNS_TXT"
+	};
+	if (isDns) return {
+		site: {
+			type: "INET_DOMAIN",
+			identifier: bareDomain(siteUrl)
+		},
+		method: chosen
+	};
+	return {
+		site: {
+			type: "SITE",
+			identifier: urlPrefix(siteUrl)
+		},
+		method: chosen
+	};
+}
+function verificationMethodsFor(site) {
+	if (site.type === "INET_DOMAIN") return ["DNS_TXT", "DNS_CNAME"];
+	return [
+		"META",
+		"FILE",
+		"ANALYTICS",
+		"TAG_MANAGER"
+	];
+}
+async function getVerificationToken(client, siteUrl, method) {
+	const { site, method: verificationMethod } = resolveVerificationTarget(siteUrl, method);
+	return {
+		...await client.verification.getToken({
+			site,
+			verificationMethod
+		}),
+		site
+	};
+}
+async function verifySite(client, siteUrl, method) {
+	const { site, method: verificationMethod } = resolveVerificationTarget(siteUrl, method);
+	return client.verification.insert({
+		site,
+		verificationMethod
+	});
+}
+async function listVerifiedSites(client) {
+	return client.verification.list();
+}
+async function getVerifiedSite(client, id) {
+	return client.verification.get(id);
+}
+async function unverifySite(client, id) {
+	return client.verification.delete(id);
+}
+export { getVerificationToken, getVerifiedSite, listVerifiedSites, resolveVerificationTarget, siteUrlToVerificationSite, unverifySite, verificationMethodsFor, verifySite };

package/dist/contracts.d.mts

@@ -1,2 +1,47 @@
-import { ColumnDef, ColumnType, GscAggregationType, GscDataState, GscResponseAggregationType, GscSearchAnalyticsDimension, GscSearchAnalyticsFilter, GscSearchAnalyticsFilterGroup, GscSearchAnalyticsFilterOperator, GscSearchAnalyticsMetadata, GscSearchAnalyticsRequest, GscSearchAnalyticsResponse, GscSearchAnalyticsRow, GscSearchType, Row, TableName, TableSchema, TenantCtx } from "./_chunks/contracts.mjs";
+import { ColumnDef, ColumnType, Row, TableName, TableSchema, TenantCtx } from "@gscdump/contracts";
+type GscSearchAnalyticsDimension = 'page' | 'query' | 'country' | 'device' | 'date' | 'hour' | 'searchAppearance';
+type GscDataState = 'final' | 'all' | 'hourly_all';
+interface GscSearchAnalyticsMetadata {
+  /** First date (YYYY-MM-DD, PT) still being collected. Populated when dataState=`all` and grouped by `date`. */
+  first_incomplete_date?: string;
+  /** First hour (YYYY-MM-DDThh:mm:ss±hh:mm, PT) still being collected. Populated when dataState=`hourly_all` and grouped by `hour`. */
+  first_incomplete_hour?: string;
+}
+type GscSearchAnalyticsFilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex';
+interface GscSearchAnalyticsFilter {
+  dimension: GscSearchAnalyticsDimension;
+  expression: string;
+  operator?: GscSearchAnalyticsFilterOperator;
+}
+interface GscSearchAnalyticsFilterGroup {
+  groupType?: 'and' | 'or';
+  filters: GscSearchAnalyticsFilter[];
+}
+type GscSearchType = 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
+type GscAggregationType = 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel';
+type GscResponseAggregationType = 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel';
+interface GscSearchAnalyticsRequest {
+  startDate: string;
+  endDate: string;
+  dimensions?: GscSearchAnalyticsDimension[];
+  dimensionFilterGroups?: GscSearchAnalyticsFilterGroup[];
+  rowLimit?: number;
+  startRow?: number;
+  /** GSC search corpus. Maps to wire field `type` (the API still accepts the deprecated `searchType` alias). */
+  type?: GscSearchType;
+  dataState?: GscDataState;
+  aggregationType?: GscAggregationType;
+}
+interface GscSearchAnalyticsRow {
+  keys: string[];
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+interface GscSearchAnalyticsResponse {
+  rows?: GscSearchAnalyticsRow[];
+  responseAggregationType?: GscResponseAggregationType;
+  metadata?: GscSearchAnalyticsMetadata;
+}
 export { type ColumnDef, type ColumnType, GscAggregationType, GscDataState, GscResponseAggregationType, GscSearchAnalyticsDimension, GscSearchAnalyticsFilter, GscSearchAnalyticsFilterGroup, GscSearchAnalyticsFilterOperator, GscSearchAnalyticsMetadata, GscSearchAnalyticsRequest, GscSearchAnalyticsResponse, GscSearchAnalyticsRow, GscSearchType, type Row, type TableName, type TableSchema, type TenantCtx };

package/dist/core/cli-format.mjs

@@ -0,0 +1,9 @@
+function rowWithMetricDefaults(row) {
+	return {
+		clicks: row.clicks ?? 0,
+		impressions: row.impressions ?? 0,
+		ctr: row.ctr ?? 0,
+		position: row.position ?? 0
+	};
+}
+export { rowWithMetricDefaults };

package/dist/core/client.d.mts

@@ -0,0 +1,122 @@
+import { GscResponseAggregationType, GscSearchAnalyticsMetadata } from "../contracts.mjs";
+import { Dimension, GSCRow } from "../query/types.mjs";
+import { GSCQueryBuilder } from "../query/builder.mjs";
+import { ApiSite, ApiSitemap, InspectUrlIndexResponse, PublishUrlNotificationResponse, SearchAnalyticsQuery, SearchAnalyticsResponse, UrlNotificationMetadata } from "./types.mjs";
+import { $Fetch, FetchOptions } from "ofetch";
+/** 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;
+export { Auth, AuthClient, AuthOptions, CallOptions, DEFAULT_GSC_REQUEST_TIMEOUT_MS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, QueryReturn, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, createAuth, createFetch, googleSearchConsole };

package/dist/core/client.mjs

@@ -0,0 +1,246 @@
+import { refreshAccessToken } from "../api/oauth.mjs";
+import { resolveToBody } from "../query/resolver.mjs";
+import { rowWithMetricDefaults } from "./cli-format.mjs";
+import { ofetch } from "ofetch";
+const GSC_API = "https://searchconsole.googleapis.com";
+const INDEXING_API = "https://indexing.googleapis.com";
+const SITE_VERIFICATION_API = "https://www.googleapis.com/siteVerification/v1";
+const DEFAULT_GSC_REQUEST_TIMEOUT_MS = 3e4;
+function encodeSiteUrl(siteUrl) {
+	if (siteUrl.startsWith("sc-domain:")) return `sc-domain:${encodeURIComponent(siteUrl.slice(10))}`;
+	return encodeURIComponent(siteUrl);
+}
+function assertValidSiteUrl(siteUrl) {
+	if (siteUrl.startsWith("sc-domain:") && siteUrl.length > 10) return;
+	if (/^https?:\/\/.+/.test(siteUrl)) return;
+	throw new Error(`Invalid siteUrl: expected "https?://…" or "sc-domain:…", got "${siteUrl}"`);
+}
+const OAUTH_EXPIRY_SKEW_MS = 6e4;
+function createAuth(options) {
+	let credentials = { refresh_token: options.refreshToken };
+	let refreshPromise = null;
+	return {
+		get credentials() {
+			return credentials;
+		},
+		async getAccessToken() {
+			if (credentials?.access_token && credentials.expiry_date && credentials.expiry_date > Date.now() + OAUTH_EXPIRY_SKEW_MS) return { token: credentials.access_token };
+			refreshPromise ??= refreshAccessToken(options.refreshToken, options.clientId, options.clientSecret).then((response) => {
+				credentials = {
+					...credentials,
+					access_token: response.accessToken,
+					expiry_date: response.expiresAt * 1e3
+				};
+				return response.accessToken;
+			}).finally(() => {
+				refreshPromise = null;
+			});
+			return { token: await refreshPromise };
+		}
+	};
+}
+async function resolveToken(auth) {
+	if (typeof auth === "string") return auth;
+	if ("accessToken" in auth && typeof auth.accessToken === "string") return auth.accessToken;
+	if ("getAccessToken" in auth && typeof auth.getAccessToken === "function") {
+		const { token } = await auth.getAccessToken();
+		return token || "";
+	}
+	if ("credentials" in auth && auth.credentials) return auth.credentials.access_token || "";
+	return "";
+}
+function createFetch(auth, options) {
+	const authState = typeof auth === "object" && auth !== null && "clientId" in auth && "refreshToken" in auth && !("getAccessToken" in auth) ? createAuth(auth) : auth;
+	return ofetch.create({
+		...options,
+		timeout: options?.timeout ?? 3e4,
+		retry: 3,
+		retryDelay: (ctx) => {
+			const status = ctx.response?.status;
+			if (status === 429 || status === 503) {
+				const header = ctx.response?.headers.get("retry-after");
+				if (header) {
+					const secs = Number.parseInt(header, 10);
+					if (Number.isFinite(secs)) return secs * 1e3;
+					const when = Date.parse(header);
+					if (Number.isFinite(when)) return Math.max(0, when - Date.now());
+				}
+			}
+			return 1e3;
+		},
+		retryStatusCodes: [
+			408,
+			425,
+			429,
+			500,
+			502,
+			503,
+			504
+		],
+		headers: {
+			...options?.headers,
+			"Accept-Encoding": "gzip",
+			"User-Agent": "gscdump (gzip)"
+		},
+		async onRequest({ options }) {
+			const token = await resolveToken(authState);
+			if (token) {
+				options.headers = new Headers(options.headers);
+				options.headers.set("Authorization", `Bearer ${token}`);
+			}
+		},
+		async onResponseError(ctx) {
+			if (ctx.response.status === 403) console.error("[gscdump] Permission denied (403). check your service account permissions being added to the GSC property.");
+			if (options?.onResponseError) if (Array.isArray(options.onResponseError)) for (const handler of options.onResponseError) await handler(ctx);
+			else await options.onResponseError(ctx);
+		}
+	});
+}
+function googleSearchConsole(auth, options = {}) {
+	let fetch;
+	const authState = typeof auth === "object" && auth !== null && "clientId" in auth && "refreshToken" in auth && !("getAccessToken" in auth) ? createAuth(auth) : auth;
+	if (options.fetch) fetch = options.fetch;
+	else {
+		const fetchOptions = { ...options.fetchOptions };
+		if (options.onRateLimited) {
+			const originalOnError = fetchOptions.onResponseError;
+			fetchOptions.onResponseError = async (ctx) => {
+				if (ctx.response.status === 429) await options.onRateLimited({ response: ctx.response });
+				if (originalOnError) if (Array.isArray(originalOnError)) for (const handler of originalOnError) await handler(ctx);
+				else await originalOnError(ctx);
+			};
+		}
+		fetch = createFetch(authState, fetchOptions);
+	}
+	const querySearchAnalytics = (siteUrl, body, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}/searchAnalytics/query`, {
+		method: "POST",
+		body,
+		signal: opts?.signal
+	});
+	return {
+		async *query(siteUrl, builder, opts) {
+			const state = builder.getState();
+			const body = resolveToBody(state);
+			const totalCap = body.rowLimit;
+			const pageSize = Math.min(totalCap ?? 25e3, 25e3);
+			let startRow = body.startRow || 0;
+			let yielded = 0;
+			let metadata;
+			let responseAggregationType;
+			while (true) {
+				opts?.signal?.throwIfAborted();
+				const remaining = totalCap ? totalCap - yielded : pageSize;
+				if (remaining <= 0) break;
+				const rowLimit = Math.min(pageSize, remaining);
+				const response = await querySearchAnalytics(siteUrl, {
+					...body,
+					startRow,
+					rowLimit
+				}, opts);
+				if (response.metadata) metadata = response.metadata;
+				if (response.responseAggregationType) responseAggregationType = response.responseAggregationType;
+				const rows = (response.rows || []).map((row) => {
+					const result = rowWithMetricDefaults(row);
+					state.dimensions.forEach((dim, i) => {
+						result[dim] = row.keys?.[i];
+					});
+					return result;
+				});
+				if (rows.length === 0) break;
+				yield rows;
+				yielded += rows.length;
+				startRow += rows.length;
+			}
+			return {
+				metadata,
+				responseAggregationType
+			};
+		},
+		sites: (() => {
+			const list = async (opts) => {
+				return (await fetch(`${GSC_API}/webmasters/v3/sites`, { signal: opts?.signal })).siteEntry || [];
+			};
+			return Object.assign(list, {
+				list,
+				get: (siteUrl, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}`, { signal: opts?.signal }),
+				add: (siteUrl, opts) => {
+					assertValidSiteUrl(siteUrl);
+					return fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}`, {
+						method: "PUT",
+						signal: opts?.signal
+					});
+				},
+				delete: (siteUrl, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}`, {
+					method: "DELETE",
+					signal: opts?.signal
+				})
+			});
+		})(),
+		verification: {
+			getToken: (params, opts) => fetch(`${SITE_VERIFICATION_API}/token`, {
+				method: "POST",
+				body: params,
+				signal: opts?.signal
+			}),
+			insert: (params, opts) => fetch(`${SITE_VERIFICATION_API}/webResource`, {
+				method: "POST",
+				query: { verificationMethod: params.verificationMethod },
+				body: { site: params.site },
+				signal: opts?.signal
+			}),
+			list: async (opts) => {
+				return (await fetch(`${SITE_VERIFICATION_API}/webResource`, { signal: opts?.signal })).items || [];
+			},
+			get: (id, opts) => fetch(`${SITE_VERIFICATION_API}/webResource/${encodeURIComponent(id)}`, { signal: opts?.signal }),
+			delete: (id, opts) => fetch(`${SITE_VERIFICATION_API}/webResource/${encodeURIComponent(id)}`, {
+				method: "DELETE",
+				signal: opts?.signal
+			})
+		},
+		inspect: (siteUrl, url, opts) => fetch(`${GSC_API}/v1/urlInspection/index:inspect`, {
+			method: "POST",
+			body: opts?.languageCode ? {
+				inspectionUrl: url,
+				siteUrl,
+				languageCode: opts.languageCode
+			} : {
+				inspectionUrl: url,
+				siteUrl
+			},
+			signal: opts?.signal
+		}),
+		sitemaps: {
+			list: async (siteUrl, opts) => {
+				return (await fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}/sitemaps`, {
+					signal: opts?.signal,
+					query: opts?.sitemapIndex ? { sitemapIndex: opts.sitemapIndex } : void 0
+				})).sitemap || [];
+			},
+			get: (siteUrl, feedpath, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, { signal: opts?.signal }),
+			submit: (siteUrl, feedpath, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, {
+				method: "PUT",
+				signal: opts?.signal
+			}),
+			delete: (siteUrl, feedpath, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, {
+				method: "DELETE",
+				signal: opts?.signal
+			})
+		},
+		indexing: {
+			publish: (url, type, opts) => fetch(`${INDEXING_API}/v3/urlNotifications:publish`, {
+				method: "POST",
+				body: {
+					url,
+					type
+				},
+				signal: opts?.signal
+			}),
+			getMetadata: (url, opts) => fetch(`${INDEXING_API}/v3/urlNotifications/metadata`, {
+				query: { url },
+				signal: opts?.signal
+			})
+		},
+		searchAnalytics: { query: querySearchAnalytics }
+	};
+}
+export { DEFAULT_GSC_REQUEST_TIMEOUT_MS, createAuth, createFetch, googleSearchConsole };

package/dist/core/errors.d.mts

@@ -0,0 +1,66 @@
+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;
+export { GscApiError, GscApiErrorInfo, GscError, GscErrorKind, classifyError, gscErrorToException, isPermissionDeniedError, parseGoogleError, rethrowAsGscApiError };