gscdump 0.4.0 → 0.5.2

package/dist/index.mjs

@@ -1,11 +1,15 @@
 import { ofetch } from "ofetch";
-
-//#region src/api/indexing.ts
-/**
-* Request Google to index or remove a URL via the Indexing API.
-* Note: The Indexing API officially supports only job posting and livestream content,
-* but can be used for any URL with varying success.
-*/
+async function runSequentialBatch(items, operation, options = {}) {
+	const { delayMs = 0, onProgress } = options;
+	const results = [];
+	for (let i = 0; i < items.length; i++) {
+		const result = await operation(items[i], i);
+		results.push(result);
+		onProgress?.(result, i, items.length);
+		if (i < items.length - 1 && delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+	}
+	return results;
+}
 async function requestIndexing(client, url, options = {}) {
 	const { type = "URL_UPDATED" } = options;
 	return client.indexing.publish(url, type).then((r) => ({
@@ -14,10 +18,6 @@ async function requestIndexing(client, url, options = {}) {
 		notifyTime: r.urlNotificationMetadata?.latestUpdate?.notifyTime || void 0
 	}));
 }
-/**
-* Get the indexing notification metadata for a URL.
-* Returns when Google was last notified about updates/removals.
-*/
 async function getIndexingMetadata(client, url) {
 	return client.indexing.getMetadata(url).then((r) => ({
 		url,
@@ -25,27 +25,13 @@ async function getIndexingMetadata(client, url) {
 		latestRemove: r.latestRemove || void 0
 	}));
 }
-/**
-* Batch request indexing for multiple URLs with rate limiting.
-* Returns results for each URL.
-*/
 async function batchRequestIndexing(client, urls, options = {}) {
 	const { type = "URL_UPDATED", delayMs = 100, onProgress } = options;
-	const results = [];
-	for (let i = 0; i < urls.length; i++) {
-		const result = await requestIndexing(client, urls[i], { type });
-		results.push(result);
-		onProgress?.(result, i, urls.length);
-		if (i < urls.length - 1 && delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
-	}
-	return results;
+	return runSequentialBatch(urls, (url) => requestIndexing(client, url, { type }), {
+		delayMs,
+		onProgress
+	});
 }
-
-//#endregion
-//#region src/api/inspection.ts
-/**
-* Inspects a URL in Google Search Console to check its indexing status.
-*/
 async function inspectUrl(client, siteUrl, inspectionUrl) {
 	const inspection = (await client.inspect(siteUrl, inspectionUrl)).inspectionResult;
 	return {
@@ -53,39 +39,23 @@ async function inspectUrl(client, siteUrl, inspectionUrl) {
 		isIndexed: inspection?.indexStatusResult?.verdict === "PASS"
 	};
 }
-/**
-* Batch inspect multiple URLs with rate limiting.
-* Returns inspection results for each URL.
-*/
 async function batchInspectUrls(client, siteUrl, urls, options = {}) {
 	const { delayMs = 200, onProgress } = options;
-	const results = [];
-	for (let i = 0; i < urls.length; i++) {
-		const url = urls[i];
+	return runSequentialBatch(urls, async (url) => {
 		const { inspection, isIndexed } = await inspectUrl(client, siteUrl, url);
-		const result = {
+		return {
 			url,
 			inspection,
 			isIndexed
 		};
-		results.push(result);
-		onProgress?.(result, i, urls.length);
-		if (i < urls.length - 1 && delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
-	}
-	return results;
+	}, {
+		delayMs,
+		onProgress
+	});
 }
-
-//#endregion
-//#region src/api/sites.ts
-/**
-* Fetches all sites the authenticated user has access to in Google Search Console.
-*/
 async function fetchSites(client) {
 	return client.sites();
 }
-/**
-* Fetches all verified sites with their sitemaps from Google Search Console.
-*/
 async function fetchSitesWithSitemaps(client) {
 	const sites = (await client.sites()).filter((s) => !!s.siteUrl && s.permissionLevel !== "siteUnverifiedUser");
 	return Promise.all(sites.map(async (site) => {
@@ -96,33 +66,122 @@ async function fetchSitesWithSitemaps(client) {
 		};
 	}));
 }
-/**
-* Fetches all sitemaps for a site.
-*/
 async function fetchSitemaps(client, siteUrl) {
 	return client.sitemaps.list(siteUrl);
 }
-/**
-* Fetches a specific sitemap.
-*/
 async function fetchSitemap(client, siteUrl, feedpath) {
 	return client.sitemaps.get(siteUrl, feedpath);
 }
-/**
-* Submits a sitemap to Google Search Console.
-*/
 async function submitSitemap(client, siteUrl, feedpath) {
 	return client.sitemaps.submit(siteUrl, feedpath);
 }
-/**
-* Deletes a sitemap from Google Search Console.
-*/
 async function deleteSitemap(client, siteUrl, feedpath) {
 	return client.sitemaps.delete(siteUrl, feedpath);
 }
-
-//#endregion
-//#region src/query/resolver.ts
+const MS_PER_DAY = 864e5;
+function toIsoDate(d) {
+	return d.toISOString().slice(0, 10);
+}
+const GSC_FINALIZED_LAG_DAYS = 3;
+const GSC_FRESHEST_LAG_DAYS = 1;
+const GSC_RETENTION_MONTHS = 16;
+function getPstDate() {
+	return (/* @__PURE__ */ new Date()).toLocaleDateString("en-CA", { timeZone: "America/Los_Angeles" });
+}
+function getPstDateDaysAgo(daysAgo) {
+	const pstNow = new Date((/* @__PURE__ */ new Date()).toLocaleString("en-US", { timeZone: "America/Los_Angeles" }));
+	pstNow.setDate(pstNow.getDate() - daysAgo);
+	return toIsoDate(pstNow);
+}
+function daysAgo(n) {
+	return toIsoDate(new Date(Date.now() - n * MS_PER_DAY));
+}
+function getLatestGscDate() {
+	return getPstDateDaysAgo(3);
+}
+function getFreshestGscDate() {
+	return getPstDateDaysAgo(1);
+}
+function getPendingDates() {
+	const dates = [];
+	for (let daysAgo = 1; daysAgo <= 3; daysAgo++) dates.push(getPstDateDaysAgo(daysAgo));
+	return dates;
+}
+function getDateRange(startDate, endDate) {
+	const dates = [];
+	const endMs = Date.parse(`${endDate}T00:00:00Z`);
+	for (let cursor = Date.parse(`${startDate}T00:00:00Z`); cursor <= endMs; cursor += MS_PER_DAY) dates.push(toIsoDate(new Date(cursor)));
+	return dates;
+}
+const DAYS_PER_RANGE = 30;
+function generateGscDateRange(startDate, endDate) {
+	const dates = [];
+	let current = startDate;
+	while (current <= endDate && isValidGscDate(current)) {
+		dates.push(current);
+		current = getNextDate(current);
+	}
+	return dates;
+}
+function groupIntoRanges(dates, daysPerRange = 30) {
+	if (dates.length === 0) return [];
+	const sorted = [...dates].sort();
+	const ranges = [];
+	let rangeStart = sorted[0];
+	let rangePrev = sorted[0];
+	for (let i = 1; i < sorted.length; i++) {
+		const current = sorted[i];
+		const expected = getNextDate(rangePrev);
+		const daysInRange = countDays(rangeStart, rangePrev);
+		if (current !== expected || daysInRange >= daysPerRange) {
+			ranges.push({
+				startDate: rangeStart,
+				endDate: rangePrev
+			});
+			rangeStart = current;
+		}
+		rangePrev = current;
+	}
+	ranges.push({
+		startDate: rangeStart,
+		endDate: rangePrev
+	});
+	return ranges;
+}
+function countDays(startDate, endDate) {
+	return Math.round((Date.parse(`${endDate}T00:00:00Z`) - Date.parse(`${startDate}T00:00:00Z`)) / MS_PER_DAY) + 1;
+}
+function getOldestGscDate() {
+	const date = /* @__PURE__ */ new Date();
+	date.setMonth(date.getMonth() - 16);
+	return toIsoDate(date);
+}
+function addDays(dateStr, n) {
+	return toIsoDate(new Date(Date.parse(`${dateStr}T00:00:00Z`) + n * MS_PER_DAY));
+}
+function getPreviousDate(dateStr) {
+	return addDays(dateStr, -1);
+}
+function getNextDate(dateStr) {
+	return addDays(dateStr, 1);
+}
+function isValidGscDate(dateStr) {
+	return dateStr >= getOldestGscDate() && dateStr <= getFreshestGscDate();
+}
+function getBackfillProgress(oldestDateSynced, newestDateSynced) {
+	if (!oldestDateSynced || !newestDateSynced) return null;
+	const oldestGsc = getOldestGscDate();
+	const newestGsc = getLatestGscDate();
+	const totalDays = Math.ceil((new Date(newestGsc).getTime() - new Date(oldestGsc).getTime()) / MS_PER_DAY);
+	const syncedDays = Math.ceil((new Date(newestDateSynced).getTime() - new Date(oldestDateSynced).getTime()) / MS_PER_DAY);
+	return {
+		progress: Math.round(Math.min(1, syncedDays / totalDays) * 100) / 100,
+		daysAvailable: totalDays,
+		daysSynced: syncedDays,
+		oldestGscDate: oldestGsc,
+		isComplete: oldestDateSynced <= oldestGsc
+	};
+}
 const DATE_OPERATORS = [
 	"gte",
 	"gt",
@@ -139,22 +198,17 @@ const METRIC_OPERATORS = [
 ];
 const SPECIAL_OPERATORS = ["topLevel"];
 const QUERY_PARAMS = ["searchType"];
+function isDateOperator(op) {
+	return DATE_OPERATORS.includes(op);
+}
 function isMetricOperator(op) {
 	return METRIC_OPERATORS.includes(op);
 }
 function isSpecialOperator(op) {
 	return SPECIAL_OPERATORS.includes(op);
 }
-function isDateOperator(op) {
-	return DATE_OPERATORS.includes(op);
-}
-function isQueryParam(dim) {
-	return QUERY_PARAMS.includes(dim);
-}
-function addDays(dateStr, days) {
-	const d = new Date(dateStr);
-	d.setDate(d.getDate() + days);
-	return d.toISOString().split("T")[0];
+function isQueryParam(value) {
+	return QUERY_PARAMS.includes(value);
 }
 function extractSpecialFilters(filter) {
 	if (!filter) return {};
@@ -244,25 +298,23 @@ function resolveFilter(filter) {
 	if (filter._nestedGroups) for (const nested of filter._nestedGroups) groups.push(...resolveFilter(nested));
 	return groups;
 }
-
-//#endregion
-//#region src/core/api-client.ts
-/**
-* Create a client that queries GSC data through gscdump.com API
-* instead of directly to Google. Useful when you don't have OAuth credentials.
-*
-* @example
-* ```ts
-* const client = gscdumpApi({ apiKey: 'gsd_user_xxx' })
-*
-* // Same query builder usage as direct client
-* for await (const rows of client.query(siteId, gsc.select('page', 'query').where(...))) {
-*   console.log(rows)
-* }
-* ```
-*/
+function rowWithMetricDefaults(row) {
+	return {
+		clicks: row.clicks ?? 0,
+		impressions: row.impressions ?? 0,
+		ctr: row.ctr ?? 0,
+		position: row.position ?? 0
+	};
+}
+function progressBar(current, total, label, width = 30) {
+	const percent = Math.min(current / total, 1);
+	const filled = Math.round(width * percent);
+	const empty = width - filled;
+	return `  ${`\x1B[36m${"█".repeat(filled)}\x1B[0m\x1B[90m${"░".repeat(empty)}\x1B[0m`} \x1B[90m${current}/${total}\x1B[0m ${label}`;
+}
+const TRAILING_SLASH_RE = /\/$/;
 function gscdumpApi(options) {
-	const baseUrl = options.baseUrl?.replace(/\/$/, "") || "https://gscdump.com";
+	const baseUrl = options.baseUrl?.replace(TRAILING_SLASH_RE, "") || "https://gscdump.com";
 	const fetch = ofetch.create({
 		baseURL: baseUrl,
 		retry: 3,
@@ -280,10 +332,11 @@ function gscdumpApi(options) {
 			"Content-Type": "application/json"
 		}
 	});
-	const rawQuery = async (siteId, body) => {
+	const rawQuery = async (siteId, body, opts) => {
 		const response = await fetch(`/api/sites/${encodeURIComponent(siteId)}/query`, {
 			method: "POST",
-			body
+			body,
+			signal: opts?.signal
 		});
 		return { rows: response.rows.map((row) => {
 			return {
@@ -296,27 +349,24 @@ function gscdumpApi(options) {
 		}) };
 	};
 	return {
-		async *query(siteId, builder) {
+		async *query(siteId, builder, opts) {
 			const state = builder.getState();
 			const body = resolveToBody(state);
 			const rowLimit = body.rowLimit || 25e3;
 			let startRow = body.startRow || 0;
 			while (true) {
+				opts?.signal?.throwIfAborted();
 				const response = await fetch(`/api/sites/${encodeURIComponent(siteId)}/query`, {
 					method: "POST",
 					body: {
 						...body,
 						startRow,
 						rowLimit
-					}
+					},
+					signal: opts?.signal
 				});
 				const rows = response.rows.map((row) => {
-					const result = {
-						clicks: row.clicks ?? 0,
-						impressions: row.impressions ?? 0,
-						ctr: row.ctr ?? 0,
-						position: row.position ?? 0
-					};
+					const result = rowWithMetricDefaults(row);
 					state.dimensions.forEach((dim) => {
 						result[dim] = row[dim];
 					});
@@ -327,8 +377,8 @@ function gscdumpApi(options) {
 				startRow += rows.length;
 			}
 		},
-		sites: async () => {
-			return (await fetch("/api/sites")).sites.map((s) => ({
+		sites: async (opts) => {
+			return (await fetch("/api/sites", { signal: opts?.signal })).sites.map((s) => ({
 				siteUrl: s.gscSiteUrl,
 				permissionLevel: s.permissionLevel || "siteOwner"
 			}));
@@ -337,8 +387,8 @@ function gscdumpApi(options) {
 			throw new Error("URL inspection not available via gscdump API. Use googleSearchConsole() with OAuth credentials.");
 		},
 		sitemaps: {
-			list: async (siteId) => {
-				return (await fetch(`/api/sites/${encodeURIComponent(siteId)}/sitemaps`)).sitemaps || [];
+			list: async (siteId, opts) => {
+				return (await fetch(`/api/sites/${encodeURIComponent(siteId)}/sitemaps`, { signal: opts?.signal })).sitemaps || [];
 			},
 			get: () => {
 				throw new Error("Sitemap get not available via gscdump API.");
@@ -361,9 +411,6 @@ function gscdumpApi(options) {
 		_rawQuery: rawQuery
 	};
 }
-
-//#endregion
-//#region src/core/client.ts
 const GSC_API = "https://searchconsole.googleapis.com";
 const INDEXING_API = "https://indexing.googleapis.com";
 function createAuth(options) {
@@ -423,11 +470,11 @@ function createFetch(auth, options) {
 			"Accept-Encoding": "gzip",
 			"User-Agent": "gscdump (gzip)"
 		},
-		async onRequest({ options: options$1 }) {
+		async onRequest({ options }) {
 			const token = await resolveToken(authState);
 			if (token) {
-				options$1.headers = new Headers(options$1.headers);
-				options$1.headers.set("Authorization", `Bearer ${token}`);
+				options.headers = new Headers(options.headers);
+				options.headers.set("Authorization", `Bearer ${token}`);
 			}
 		},
 		async onResponseError(ctx) {
@@ -453,28 +500,25 @@ function googleSearchConsole(auth, options = {}) {
 		}
 		fetch = createFetch(authState, fetchOptions);
 	}
-	const rawQuery = (siteUrl, body) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/searchAnalytics/query`, {
+	const rawQuery = (siteUrl, body, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/searchAnalytics/query`, {
 		method: "POST",
-		body
+		body,
+		signal: opts?.signal
 	});
 	return {
-		async *query(siteUrl, builder) {
+		async *query(siteUrl, builder, opts) {
 			const state = builder.getState();
 			const body = resolveToBody(state);
 			const rowLimit = body.rowLimit || 25e3;
 			let startRow = body.startRow || 0;
 			while (true) {
+				opts?.signal?.throwIfAborted();
 				const rows = ((await rawQuery(siteUrl, {
 					...body,
 					startRow,
 					rowLimit
-				})).rows || []).map((row) => {
-					const result = {
-						clicks: row.clicks ?? 0,
-						impressions: row.impressions ?? 0,
-						ctr: row.ctr ?? 0,
-						position: row.position ?? 0
-					};
+				}, opts)).rows || []).map((row) => {
+					const result = rowWithMetricDefaults(row);
 					state.dimensions.forEach((dim, i) => {
 						result[dim] = row.keys?.[i];
 					});
@@ -485,183 +529,271 @@ function googleSearchConsole(auth, options = {}) {
 				startRow += rows.length;
 			}
 		},
-		sites: async () => {
-			return (await fetch(`${GSC_API}/webmasters/v3/sites`)).siteEntry || [];
+		sites: async (opts) => {
+			return (await fetch(`${GSC_API}/webmasters/v3/sites`, { signal: opts?.signal })).siteEntry || [];
 		},
-		inspect: (siteUrl, url) => fetch(`${GSC_API}/v1/urlInspection/index:inspect`, {
+		inspect: (siteUrl, url, opts) => fetch(`${GSC_API}/v1/urlInspection/index:inspect`, {
 			method: "POST",
 			body: {
 				inspectionUrl: url,
 				siteUrl
-			}
+			},
+			signal: opts?.signal
 		}),
 		sitemaps: {
-			list: async (siteUrl) => {
-				return (await fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps`)).sitemap || [];
+			list: async (siteUrl, opts) => {
+				return (await fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps`, { signal: opts?.signal })).sitemap || [];
 			},
-			get: (siteUrl, feedpath) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`),
-			submit: (siteUrl, feedpath) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, { method: "PUT" }),
-			delete: (siteUrl, feedpath) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, { method: "DELETE" })
+			get: (siteUrl, feedpath, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, { signal: opts?.signal }),
+			submit: (siteUrl, feedpath, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, {
+				method: "PUT",
+				signal: opts?.signal
+			}),
+			delete: (siteUrl, feedpath, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeURIComponent(siteUrl)}/sitemaps/${encodeURIComponent(feedpath)}`, {
+				method: "DELETE",
+				signal: opts?.signal
+			})
 		},
 		indexing: {
-			publish: (url, type) => fetch(`${INDEXING_API}/v3/urlNotifications:publish`, {
+			publish: (url, type, opts) => fetch(`${INDEXING_API}/v3/urlNotifications:publish`, {
 				method: "POST",
 				body: {
 					url,
 					type
-				}
+				},
+				signal: opts?.signal
 			}),
-			getMetadata: (url) => fetch(`${INDEXING_API}/v3/urlNotifications/metadata`, { query: { url } })
+			getMetadata: (url, opts) => fetch(`${INDEXING_API}/v3/urlNotifications/metadata`, {
+				query: { url },
+				signal: opts?.signal
+			})
 		},
 		_rawQuery: rawQuery
 	};
 }
-
-//#endregion
-//#region src/core/errors.ts
-/** GSC API quota limits (approximate) */
 const GSC_QUOTAS = {
 	searchAnalytics: 25e3,
 	urlInspection: 2e3,
 	indexing: 200
 };
-/**
-* Detects if an error is a quota exceeded error (403 quotaExceeded).
-*/
-function isQuotaError(error) {
-	const msg = getErrorMessage(error).toLowerCase();
-	return getErrorCode(error) === 403 && (msg.includes("quota") || msg.includes("limit exceeded") || msg.includes("rate limit") || msg.includes("quotaexceeded"));
-}
-/**
-* Detects if an error is a rate limit error (429 Too Many Requests).
-*/
-function isRateLimitError(error) {
-	return getErrorCode(error) === 429;
-}
-/**
-* Detects if an error is an authentication error (401/403 without quota).
-*/
-function isAuthError(error) {
-	const code = getErrorCode(error);
-	const msg = getErrorMessage(error).toLowerCase();
-	if (code === 401) return true;
-	if (code === 403 && !isQuotaError(error)) return msg.includes("access") || msg.includes("permission") || msg.includes("forbidden");
-	return false;
-}
-/**
-* Extracts HTTP status code from various error formats.
-*/
-function getErrorCode(error) {
+function pickField(error, paths, is) {
 	if (!error || typeof error !== "object") return void 0;
-	const e = error;
-	if ("statusCode" in e && typeof e.statusCode === "number") return e.statusCode;
-	if ("status" in e && typeof e.status === "number") return e.status;
-	if ("response" in e && e.response && typeof e.response === "object") {
-		const resp = e.response;
-		if ("status" in resp && typeof resp.status === "number") return resp.status;
+	for (const path of paths) {
+		let current = error;
+		for (const key of path) {
+			if (!current || typeof current !== "object") {
+				current = void 0;
+				break;
+			}
+			current = current[key];
+		}
+		if (is(current)) return current;
 	}
-	if ("code" in e && typeof e.code === "number") return e.code;
 }
-/**
-* Extracts error message from various error formats.
-*/
-function getErrorMessage(error) {
+const isNumber = (v) => typeof v === "number";
+const isString = (v) => typeof v === "string";
+function extractStatus(error) {
+	return pickField(error, [
+		["statusCode"],
+		["status"],
+		["response", "status"],
+		["code"]
+	], isNumber);
+}
+function extractMessage(error) {
 	if (!error) return "Unknown error";
 	if (typeof error === "string") return error;
 	if (error instanceof Error) return error.message;
-	if (typeof error === "object") {
-		const e = error;
-		if ("message" in e && typeof e.message === "string") return e.message;
-		if ("statusMessage" in e && typeof e.statusMessage === "string") return e.statusMessage;
-		if ("data" in e && e.data && typeof e.data === "object") {
-			const data = e.data;
-			if ("error" in data && data.error && typeof data.error === "object") {
-				const err = data.error;
-				if ("message" in err && typeof err.message === "string") return err.message;
-			}
-		}
+	if (typeof error !== "object") return String(error);
+	return pickField(error, [
+		[
+			"data",
+			"error",
+			"message"
+		],
+		["message"],
+		["statusMessage"]
+	], isString) ?? String(error);
+}
+function extractRetryAfter(error) {
+	const raw = pickField(error, [
+		["headers", "retry-after"],
+		["headers", "Retry-After"],
+		[
+			"response",
+			"headers",
+			"retry-after"
+		],
+		[
+			"response",
+			"headers",
+			"Retry-After"
+		]
+	], (v) => typeof v === "number" || typeof v === "string");
+	if (typeof raw === "number") return raw;
+	if (typeof raw === "string") {
+		const seconds = Number.parseInt(raw, 10);
+		return Number.isNaN(seconds) ? void 0 : seconds;
 	}
-	return String(error);
 }
-/**
-* Extracts retry-after value from error headers (in seconds).
-*/
-function getRetryAfter(error) {
-	if (!error || typeof error !== "object") return void 0;
-	const e = error;
-	if ("headers" in e && e.headers && typeof e.headers === "object") {
-		const headers = e.headers;
-		const retryAfter = headers["retry-after"] || headers["Retry-After"];
-		if (typeof retryAfter === "string") {
-			const seconds = Number.parseInt(retryAfter, 10);
-			return Number.isNaN(seconds) ? void 0 : seconds;
-		}
-		if (typeof retryAfter === "number") return retryAfter;
+const QUOTA_MESSAGE_RE = /quota|rate\s*limit/i;
+function classifyError(cause) {
+	const status = extractStatus(cause);
+	const message = extractMessage(cause);
+	if (status === 401) return {
+		kind: "auth-expired",
+		message,
+		cause
+	};
+	if (status === 429) return {
+		kind: "rate-limited",
+		message,
+		retryAfter: extractRetryAfter(cause),
+		cause
+	};
+	if (status === 403) {
+		if (QUOTA_MESSAGE_RE.test(message)) return {
+			kind: "rate-limited",
+			message,
+			retryAfter: extractRetryAfter(cause),
+			cause
+		};
+		return {
+			kind: "auth-expired",
+			message,
+			cause
+		};
 	}
-}
-function formatQuotaSuggestion(message, retryAfter) {
-	if (message.includes("Search Console API")) return `You exceeded the Search Analytics quota (${GSC_QUOTAS.searchAnalytics}/day). Try again tomorrow.`;
-	if (message.includes("Indexing API")) return `You exceeded the Indexing API quota (${GSC_QUOTAS.indexing}/day). Try again tomorrow.`;
-	return `Quota exceeded. Try again in ${retryAfter ? `${retryAfter}s` : "24 hours"}.`;
-}
-function formatRateLimitSuggestion(retryAfter) {
-	return `Rate limited. Slow down requests. Try again in ${retryAfter ? `${retryAfter}s` : "a few minutes"}.`;
-}
-/**
-* Analyzes an error and returns structured information with suggestions.
-*/
-function analyzeError(error) {
-	const code = getErrorCode(error);
-	const message = getErrorMessage(error);
-	const retryAfter = getRetryAfter(error);
-	if (isQuotaError(error)) return {
-		isQuotaError: true,
-		isRateLimitError: false,
-		isAuthError: false,
-		code,
+	if (status === 404) return {
+		kind: "not-found",
 		message,
-		retryAfter,
-		suggestion: formatQuotaSuggestion(message, retryAfter)
+		cause
 	};
-	if (isRateLimitError(error)) return {
-		isQuotaError: false,
-		isRateLimitError: true,
-		isAuthError: false,
-		code,
+	if (status === 400 || status === 422) return {
+		kind: "validation",
 		message,
-		retryAfter: retryAfter || 60,
-		suggestion: formatRateLimitSuggestion(retryAfter)
+		cause
 	};
-	if (isAuthError(error)) return {
-		isQuotaError: false,
-		isRateLimitError: false,
-		isAuthError: true,
-		code,
+	return {
+		kind: "transport",
 		message,
-		suggestion: "Run `gscdump auth` to re-authenticate."
+		status,
+		cause
 	};
+}
+function storageError(message, cause) {
 	return {
-		isQuotaError: false,
-		isRateLimitError: false,
-		isAuthError: false,
-		code,
+		kind: "storage",
 		message,
-		suggestion: ""
+		cause
 	};
 }
-/**
-* Formats an error for CLI display with color codes.
-*/
-function formatErrorForCli(error) {
-	const info = analyzeError(error);
-	const lines = [];
-	lines.push(`\x1B[31m${info.message}\x1B[0m`);
-	if (info.suggestion) {
+const PERMISSION_SIGNALS = [
+	"403 forbidden",
+	"permission_denied",
+	"does not have sufficient permission",
+	"insufficient permission"
+];
+function isPermissionDeniedError(err) {
+	const msg = String(err?.message ?? err ?? "").toLowerCase();
+	return PERMISSION_SIGNALS.some((s) => msg.includes(s));
+}
+function suggestionFor(err) {
+	switch (err.kind) {
+		case "auth-expired": return "Run `gscdump auth` to re-authenticate.";
+		case "rate-limited": {
+			const retryIn = err.retryAfter ? `${err.retryAfter}s` : "a few minutes";
+			if (QUOTA_MESSAGE_RE.test(err.message)) {
+				if (err.message.includes("Indexing API")) return `Indexing API quota exhausted (~${GSC_QUOTAS.indexing}/day). Try again tomorrow.`;
+				return `Quota or rate limit hit (Search Analytics ~${GSC_QUOTAS.searchAnalytics}/day). Try again in ${retryIn}.`;
+			}
+			return `Rate limited. Slow down requests. Try again in ${retryIn}.`;
+		}
+		case "not-found":
+		case "validation":
+		case "storage":
+		case "transport": return "";
+	}
+}
+function formatErrorForCli(cause) {
+	const err = classifyError(cause);
+	const lines = [`\x1B[31m${err.message}\x1B[0m`];
+	const suggestion = suggestionFor(err);
+	if (suggestion) {
 		lines.push("");
-		lines.push(info.suggestion);
+		lines.push(suggestion);
 	}
 	return lines.join("\n");
 }
-
-//#endregion
-export { GSC_QUOTAS, analyzeError, batchInspectUrls, batchRequestIndexing, createAuth, createFetch, deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, getErrorCode, getErrorMessage, getIndexingMetadata, getRetryAfter, googleSearchConsole, gscdumpApi, inspectUrl, isAuthError, isQuotaError, isRateLimitError, requestIndexing, submitSitemap };
+const INDEXING_ISSUE_FILTERS = {
+	canonical_mismatch: `user_canonical IS NOT NULL AND google_canonical IS NOT NULL AND user_canonical != google_canonical`,
+	stale_crawl: `last_crawl_time < datetime('now', '-30 days')`,
+	very_stale_crawl: `last_crawl_time < datetime('now', '-60 days')`,
+	not_indexed: `verdict IN ('FAIL', 'PARTIAL', 'NEUTRAL')`,
+	unknown_to_google: `coverage_state = 'URL is unknown to Google'`,
+	crawled_not_indexed: `coverage_state LIKE '%Crawled%not indexed%' OR coverage_state LIKE '%Discovered%not indexed%'`,
+	not_found: `page_fetch_state = 'NOT_FOUND' OR coverage_state = 'Not found (404)'`,
+	soft_404: `page_fetch_state = 'SOFT_404'`,
+	server_error: `page_fetch_state = 'SERVER_ERROR'`,
+	blocked_robots: `robots_txt_state = 'DISALLOWED'`,
+	noindex: `indexing_state LIKE '%noindex%' OR coverage_state LIKE '%noindex%'`,
+	redirect: `coverage_state = 'Page with redirect'`,
+	fragment_url: `url LIKE '%#%'`,
+	mobile_fail: `mobile_verdict IN ('FAIL', 'PARTIAL')`,
+	rich_results_fail: `rich_results_verdict = 'FAIL'`,
+	rich_results_warning: `rich_results_verdict = 'PARTIAL'`,
+	rich_results_pass: `rich_results_verdict = 'PASS'`
+};
+const INDEXING_ISSUE_LABELS = {
+	canonical_mismatch: "Canonical mismatch",
+	stale_crawl: "Not crawled in 30+ days",
+	very_stale_crawl: "Not crawled in 60+ days",
+	not_indexed: "Not indexed",
+	unknown_to_google: "Unknown to Google",
+	crawled_not_indexed: "Crawled but not indexed",
+	not_found: "404 Not Found",
+	soft_404: "Soft 404",
+	server_error: "Server error",
+	blocked_robots: "Blocked by robots.txt",
+	noindex: "Noindex tag",
+	redirect: "Redirect",
+	fragment_url: "Fragment URL (#)",
+	mobile_fail: "Mobile usability issues",
+	rich_results_fail: "Rich results errors",
+	rich_results_warning: "Rich results warnings",
+	rich_results_pass: "Has rich results"
+};
+const INDEXING_ISSUE_SEVERITY = {
+	canonical_mismatch: "warning",
+	stale_crawl: "info",
+	very_stale_crawl: "warning",
+	not_indexed: "error",
+	unknown_to_google: "warning",
+	crawled_not_indexed: "error",
+	not_found: "error",
+	soft_404: "error",
+	server_error: "error",
+	blocked_robots: "warning",
+	noindex: "info",
+	redirect: "info",
+	fragment_url: "warning",
+	mobile_fail: "warning",
+	rich_results_fail: "error",
+	rich_results_warning: "warning",
+	rich_results_pass: "info"
+};
+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");
+}
+export { DAYS_PER_RANGE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_QUOTAS, GSC_RETENTION_MONTHS, INDEXING_DAILY_LIMIT, INDEXING_EFFECTIVE_LIMIT, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, MS_PER_DAY, addDays, batchInspectUrls, batchRequestIndexing, classifyError, countDays, createAuth, createFetch, daysAgo, deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, formatErrorForCli, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingMetadata, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, googleSearchConsole, groupIntoRanges, gscdumpApi, hasGscReadScope, hasGscWriteScope, hasIndexingScope, inspectUrl, isPermissionDeniedError, isValidGscDate, progressBar, requestIndexing, rowWithMetricDefaults, storageError, submitSitemap, toIsoDate };