gscdump 0.40.2 → 1.0.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { ofetch } from "ofetch";
-import { GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSCDUMP_WRITE_ANALYTICS_SCOPE, accountNextActions, accountStatuses, analyticsNextActions, analyticsStatuses, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, lifecycleErrorCodes, lifecycleWebhookEvents, parseGrantedScopes, propertyNextActions, propertyStatuses, querySourceModes, sitemapNextActions, sitemapStatuses } from "@gscdump/contracts/partner";
+import { GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSCDUMP_WRITE_ANALYTICS_SCOPE, accountNextActions, accountStatuses, analyticsNextActions, analyticsStatuses, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, lifecycleErrorCodes, parseGrantedScopes, propertyNextActions, propertyStatuses, querySourceModes, sitemapNextActions, sitemapStatuses } from "@gscdump/contracts/partner";
 async function runSequentialBatch(items, operation, options = {}) {
 	const { delayMs = 0, concurrency = 1, onProgress } = options;
 	const results = Array.from({ length: items.length });
@@ -96,8 +96,8 @@ async function batchInspectUrls(client, siteUrl, urls, options = {}) {
 		onProgress
 	});
 }
-async function inspectUrlFlat(client, siteUrl, inspectionUrl) {
-	const inspection = (await client.inspect(siteUrl, inspectionUrl)).inspectionResult;
+async function inspectUrlFlat(client, siteUrl, inspectionUrl, options) {
+	const inspection = (await client.inspect(siteUrl, inspectionUrl, options)).inspectionResult;
 	const index = inspection?.indexStatusResult;
 	const mobile = inspection?.mobileUsabilityResult;
 	const rich = inspection?.richResultsResult;
@@ -130,6 +130,30 @@ async function inspectUrlFlat(client, siteUrl, inspectionUrl) {
 		inspectionResultLink: inspection?.inspectionResultLink ?? null
 	};
 }
+const MAX_FLAT_INSPECTION_BATCH_CONCURRENCY = 10;
+async function batchInspectUrlsFlatSettled(client, siteUrl, urls, options = {}) {
+	const requestedConcurrency = Math.trunc(options.concurrency ?? 1);
+	const concurrency = Number.isFinite(requestedConcurrency) ? Math.max(1, Math.min(requestedConcurrency, 10)) : 1;
+	return runSequentialBatch([...urls], async (url) => {
+		try {
+			return {
+				url,
+				status: "fulfilled",
+				value: await inspectUrlFlat(client, siteUrl, url, { signal: options.signal })
+			};
+		} catch (reason) {
+			return {
+				url,
+				status: "rejected",
+				reason
+			};
+		}
+	}, {
+		delayMs: options.delayMs ?? 200,
+		concurrency,
+		onProgress: options.onProgress
+	});
+}
 function getNextCheckPriority(result) {
 	if (!result.verdict || result.verdict === "VERDICT_UNSPECIFIED") return "medium";
 	if (result.verdict === "FAIL" || result.verdict === "PARTIAL" || result.verdict === "NEUTRAL") return "high";
@@ -175,11 +199,6 @@ function getIndexingEligibility(grantedScopes, permissionLevel) {
 		grantedScopes: scopes
 	};
 }
-const GSC_QUOTAS = {
-	searchAnalytics: 25e3,
-	urlInspection: 2e3,
-	indexing: 200
-};
 function pickField(error, paths, is) {
 	if (!error || typeof error !== "object") return void 0;
 	for (const path of paths) {
@@ -323,13 +342,6 @@ function classifyError(cause) {
 		cause
 	};
 }
-function storageError(message, cause) {
-	return {
-		kind: "storage",
-		message,
-		cause
-	};
-}
 function gscErrorToException(error) {
 	const exception = new Error(error.message);
 	if (error.cause !== void 0) exception.cause = error.cause;
@@ -393,33 +405,6 @@ 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(suggestion);
-	}
-	return lines.join("\n");
-}
 function ok(value) {
 	return {
 		ok: true,
@@ -438,20 +423,13 @@ function isOk(result) {
 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_TOKEN_INFO_URL = "https://oauth2.googleapis.com/tokeninfo";
+const OAUTH_REVOKE_URL = "https://oauth2.googleapis.com/revoke";
 const OAUTH_TIMEOUT_MS = 8e3;
 const OAUTH_MAX_ATTEMPTS = 3;
 const OAUTH_BACKOFF_MS = [
@@ -460,12 +438,18 @@ const OAUTH_BACKOFF_MS = [
 	1500
 ];
 async function refreshAccessTokenResult(refreshToken, clientId, clientSecret) {
-	return postOAuthTokenResult(new URLSearchParams({
+	const result = await postOAuthTokenResult(new URLSearchParams({
 		client_id: clientId,
 		client_secret: clientSecret,
 		refresh_token: refreshToken,
 		grant_type: "refresh_token"
 	}), "refresh");
+	if (!result.ok) return result;
+	return ok({
+		accessToken: result.value.accessToken,
+		expiresAt: result.value.expiresAt,
+		scope: result.value.scope
+	});
 }
 async function refreshAccessToken(refreshToken, clientId, clientSecret) {
 	return unwrapResult(await refreshAccessTokenResult(refreshToken, clientId, clientSecret), oauthErrorToException);
@@ -479,19 +463,46 @@ async function exchangeAuthCodeResult(code, clientId, clientSecret, redirectUri)
 		grant_type: "authorization_code"
 	}), "exchange");
 	if (!result.ok) return result;
-	const refreshToken = result.value.refresh_token;
+	return result;
+}
+async function introspectAccessTokenResult(accessToken) {
+	const response = await requestOAuthResult(`${OAUTH_TOKEN_INFO_URL}?access_token=${encodeURIComponent(accessToken)}`, { method: "GET" }, "introspect");
+	if (!response.ok) return response;
+	const parsed = await readOAuthJsonResult(response.value, "introspect");
+	if (!parsed.ok) return parsed;
+	const data = parsed.value;
 	return ok({
-		...result.value,
-		refreshToken
+		issuedTo: optionalString(data.issued_to),
+		audience: optionalString(data.aud),
+		authorizedParty: optionalString(data.azp),
+		userId: optionalString(data.user_id),
+		subject: optionalString(data.sub),
+		scope: optionalString(data.scope),
+		expiresIn: optionalNumber(data.expires_in),
+		expiresAt: optionalNumber(data.exp),
+		email: optionalString(data.email),
+		emailVerified: optionalBoolean(data.email_verified),
+		accessType: optionalString(data.access_type)
 	});
 }
-async function exchangeAuthCode(code, clientId, clientSecret, redirectUri) {
-	return unwrapResult(await exchangeAuthCodeResult(code, clientId, clientSecret, redirectUri), oauthErrorToException);
+async function introspectAccessToken(accessToken) {
+	return unwrapResult(await introspectAccessTokenResult(accessToken), oauthErrorToException);
+}
+async function revokeOAuthTokenResult(token) {
+	const response = await requestOAuthResult(OAUTH_REVOKE_URL, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({ token })
+	}, "revoke");
+	return response.ok ? ok(void 0) : response;
+}
+async function revokeOAuthToken(token) {
+	return unwrapResult(await revokeOAuthTokenResult(token), 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 ? {
+	return info.reason === "invalid_grant" || info.reason === "invalid_token" || info.code === 400 || info.code === 401 || info.code === 403 ? {
 		kind: "auth-expired",
 		message,
 		cause
@@ -506,13 +517,28 @@ function oauthErrorToException(error) {
 	return error.cause instanceof Error ? error.cause : gscErrorToException(error);
 }
 async function postOAuthTokenResult(body, op) {
+	const response = await requestOAuthResult(OAUTH_TOKEN_URL, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body
+	}, op);
+	if (!response.ok) return response;
+	const parsed = await readOAuthJsonResult(response.value, op);
+	if (!parsed.ok) return parsed;
+	const data = parsed.value;
+	return ok({
+		accessToken: data.access_token,
+		expiresAt: Math.floor(Date.now() / 1e3) + data.expires_in,
+		refreshToken: data.refresh_token,
+		scope: data.scope
+	});
+}
+async function requestOAuthResult(url, init, 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]));
-		const res = await fetch(OAUTH_TOKEN_URL, {
-			method: "POST",
-			headers: { "Content-Type": "application/x-www-form-urlencoded" },
-			body,
+		const res = await fetch(url, {
+			...init,
 			signal: AbortSignal.timeout(OAUTH_TIMEOUT_MS)
 		}).catch((error) => {
 			lastError = error;
@@ -520,12 +546,7 @@ async function postOAuthTokenResult(body, op) {
 		});
 		if (!res) continue;
 		if (!res.ok) return err(oauthHttpError(op, parseGoogleError(await res.text(), res.status)));
-		const data = await res.json();
-		return ok({
-			accessToken: data.access_token,
-			expiresAt: Math.floor(Date.now() / 1e3) + data.expires_in,
-			refresh_token: data.refresh_token
-		});
+		return ok(res);
 	}
 	return err({
 		kind: "transport",
@@ -533,6 +554,30 @@ async function postOAuthTokenResult(body, op) {
 		cause: lastError
 	});
 }
+async function readOAuthJsonResult(response, op) {
+	try {
+		return ok(await response.json());
+	} catch (cause) {
+		return err({
+			kind: "transport",
+			message: `Failed to parse ${op} token response`,
+			status: response.status,
+			cause
+		});
+	}
+}
+function optionalString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function optionalNumber(value) {
+	const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
+function optionalBoolean(value) {
+	if (typeof value === "boolean") return value;
+	if (value === "true") return true;
+	if (value === "false") return false;
+}
 async function fetchSites(client) {
 	return client.sites();
 }
@@ -668,9 +713,6 @@ function getPstDateDaysAgo(daysAgo) {
 	pstNow.setDate(pstNow.getDate() - daysAgo);
 	return toIsoDate(pstNow);
 }
-function daysAgo(n) {
-	return toIsoDate(/* @__PURE__ */ new Date(Date.now() - n * MS_PER_DAY));
-}
 function getLatestGscDate() {
 	return getPstDateDaysAgo(3);
 }
@@ -2328,6 +2370,12 @@ const queryErrors = {
 			message: "Invalid state"
 		};
 	},
+	malformedFilterLeaf() {
+		return {
+			kind: "invalid-filter",
+			message: "Malformed filter: each filter leaf requires a string `dimension` and `operator`"
+		};
+	},
 	unsupportedCapability(capability, context) {
 		return {
 			kind: "unsupported-capability",
@@ -2534,152 +2582,10 @@ function rowWithMetricDefaults(row) {
 		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(TRAILING_SLASH_RE, "") || "https://gscdump.com";
-	const fetch = ofetch.create({
-		baseURL: baseUrl,
-		retry: 3,
-		retryDelay: 1e3,
-		retryStatusCodes: [
-			408,
-			425,
-			429,
-			500,
-			502,
-			503,
-			504
-		],
-		headers: {
-			"x-api-key": options.apiKey,
-			"Content-Type": "application/json"
-		}
-	});
-	const rawQuery = async (siteId, body, opts) => {
-		const response = await fetch(`/api/sites/${encodeURIComponent(siteId)}/query`, {
-			method: "POST",
-			body,
-			signal: opts?.signal
-		});
-		return { rows: response.rows.map((row) => {
-			return {
-				keys: response.meta.dimensions.map((dim) => String(row[dim] ?? "")),
-				clicks: row.clicks,
-				impressions: row.impressions,
-				ctr: row.ctr,
-				position: row.position
-			};
-		}) };
-	};
-	return {
-		async *query(siteId, 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;
-			while (true) {
-				opts?.signal?.throwIfAborted();
-				const remaining = totalCap ? totalCap - yielded : pageSize;
-				if (remaining <= 0) break;
-				const rowLimit = Math.min(pageSize, remaining);
-				const response = await fetch(`/api/sites/${encodeURIComponent(siteId)}/query`, {
-					method: "POST",
-					body: {
-						...body,
-						startRow,
-						rowLimit
-					},
-					signal: opts?.signal
-				});
-				if (response.metadata) metadata = response.metadata;
-				const rows = response.rows.map((row) => {
-					const result = rowWithMetricDefaults(row);
-					state.dimensions.forEach((dim) => {
-						result[dim] = row[dim];
-					});
-					return result;
-				});
-				yield rows;
-				yielded += rows.length;
-				if (!response.meta.hasMore || rows.length < rowLimit) break;
-				startRow += rows.length;
-			}
-			return { metadata };
-		},
-		sites: (() => {
-			const list = async (opts) => {
-				return (await fetch("/api/sites", { signal: opts?.signal })).sites.map((s) => ({
-					siteUrl: s.gscSiteUrl,
-					permissionLevel: s.permissionLevel || "siteOwner"
-				}));
-			};
-			const unsupported = (op) => () => {
-				throw new Error(`sites.${op} not available via gscdump API. Use googleSearchConsole() with OAuth credentials.`);
-			};
-			return Object.assign(list, {
-				list,
-				get: unsupported("get"),
-				add: unsupported("add"),
-				delete: unsupported("delete")
-			});
-		})(),
-		verification: {
-			getToken: () => {
-				throw new Error("Site Verification API not available via gscdump API. Use googleSearchConsole() with OAuth credentials.");
-			},
-			insert: () => {
-				throw new Error("Site Verification API not available via gscdump API. Use googleSearchConsole() with OAuth credentials.");
-			},
-			list: () => {
-				throw new Error("Site Verification API not available via gscdump API. Use googleSearchConsole() with OAuth credentials.");
-			},
-			get: () => {
-				throw new Error("Site Verification API not available via gscdump API. Use googleSearchConsole() with OAuth credentials.");
-			},
-			delete: () => {
-				throw new Error("Site Verification API not available via gscdump API. Use googleSearchConsole() with OAuth credentials.");
-			}
-		},
-		inspect: () => {
-			throw new Error("URL inspection not available via gscdump API. Use googleSearchConsole() with OAuth credentials.");
-		},
-		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.");
-			},
-			submit: () => {
-				throw new Error("Sitemap submit not available via gscdump API.");
-			},
-			delete: () => {
-				throw new Error("Sitemap delete not available via gscdump API.");
-			}
-		},
-		indexing: {
-			publish: () => {
-				throw new Error("Indexing API not available via gscdump API. Use googleSearchConsole() with OAuth credentials.");
-			},
-			getMetadata: () => {
-				throw new Error("Indexing API not available via gscdump API. Use googleSearchConsole() with OAuth credentials.");
-			}
-		},
-		_rawQuery: rawQuery
-	};
-}
 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);
@@ -2689,6 +2595,7 @@ function assertValidSiteUrl(siteUrl) {
 	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;
@@ -2697,22 +2604,14 @@ function createAuth(options) {
 			return credentials;
 		},
 		async getAccessToken() {
-			if (credentials?.access_token && credentials.expiry_date && credentials.expiry_date > Date.now()) return { token: credentials.access_token };
-			refreshPromise ??= ofetch("https://oauth2.googleapis.com/token", {
-				method: "POST",
-				body: new URLSearchParams({
-					client_id: options.clientId,
-					client_secret: options.clientSecret,
-					refresh_token: options.refreshToken,
-					grant_type: "refresh_token"
-				})
-			}).then((response) => {
+			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.access_token,
-					expiry_date: Date.now() + response.expires_in * 1e3
+					access_token: response.accessToken,
+					expiry_date: response.expiresAt * 1e3
 				};
-				return response.access_token;
+				return response.accessToken;
 			}).finally(() => {
 				refreshPromise = null;
 			});
@@ -2734,6 +2633,7 @@ 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;
@@ -2781,7 +2681,7 @@ function googleSearchConsole(auth, options = {}) {
 	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 || {};
+		const fetchOptions = { ...options.fetchOptions };
 		if (options.onRateLimited) {
 			const originalOnError = fetchOptions.onResponseError;
 			fetchOptions.onResponseError = async (ctx) => {
@@ -2792,7 +2692,7 @@ function googleSearchConsole(auth, options = {}) {
 		}
 		fetch = createFetch(authState, fetchOptions);
 	}
-	const rawQuery = (siteUrl, body, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}/searchAnalytics/query`, {
+	const querySearchAnalytics = (siteUrl, body, opts) => fetch(`${GSC_API}/webmasters/v3/sites/${encodeSiteUrl(siteUrl)}/searchAnalytics/query`, {
 		method: "POST",
 		body,
 		signal: opts?.signal
@@ -2812,7 +2712,7 @@ function googleSearchConsole(auth, options = {}) {
 				const remaining = totalCap ? totalCap - yielded : pageSize;
 				if (remaining <= 0) break;
 				const rowLimit = Math.min(pageSize, remaining);
-				const response = await rawQuery(siteUrl, {
+				const response = await querySearchAnalytics(siteUrl, {
 					...body,
 					startRow,
 					rowLimit
@@ -2920,7 +2820,7 @@ function googleSearchConsole(auth, options = {}) {
 				signal: opts?.signal
 			})
 		},
-		_rawQuery: rawQuery
+		searchAnalytics: { query: querySearchAnalytics }
 	};
 }
 const INDEXING_ISSUE_FILTERS = {
@@ -3162,7 +3062,6 @@ function findExactGscProperty(propertyUrl, properties) {
 function formatGscPropertyCandidates(candidates) {
 	return candidates.filter((c) => !!c).map((property) => `${property.siteUrl} (${property.permissionLevel})`).join(", ");
 }
-const URL_INSPECTION_DAILY_LIMIT = 2e3;
 const URL_INSPECTION_EFFECTIVE_LIMIT = 1800;
 const URL_PROTOCOL_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
 function normalizeUrl(input) {
@@ -3270,4 +3169,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, GSCDUMP_WRITE_ANALYTICS_SCOPE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_INDEXING_SCOPE, GSC_QUOTAS, GSC_READ_SCOPE, GSC_RETENTION_MONTHS, GSC_SITE_VERIFICATION_SCOPE, GSC_WRITE_SCOPE, GscApiError, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, KNOWN_COVERAGE_STATES, KNOWN_PAGE_FETCH_STATES, 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, hasGoogleScope, 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, parseGoogleScopes, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, progressBar, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, refreshAccessTokenResult, requestIndexing, resolveVerificationTarget, rethrowAsGscApiError, rowWithMetricDefaults, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, storageError, submitSitemap, toIsoDate, unmappedInspectionReasons, unverifySite, unwrapResult, urlMatchKey, verificationMethodsFor, verifySite };
+export { DAYS_PER_RANGE, DEFAULT_GSC_REQUEST_TIMEOUT_MS, 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, GscApiError, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, KNOWN_COVERAGE_STATES, KNOWN_PAGE_FETCH_STATES, MAX_FLAT_INSPECTION_BATCH_CONCURRENCY, MS_PER_DAY, URL_INSPECTION_EFFECTIVE_LIMIT, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchInspectUrlsFlatSettled, batchRequestIndexing, canUseUrlInspection, classifyError, countDays, createAuth, createFetch, decodeSiteId, deleteSite, deleteSitemap, discoverSitemap, encodeSiteId, err, exchangeAuthCodeResult, fetchSitemap, fetchSitemapUrls, 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, isErr, isOk, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, listVerifiedSites, matchGscSite, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, ok, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, resolveVerificationTarget, rethrowAsGscApiError, revokeOAuthToken, revokeOAuthTokenResult, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, submitSitemap, toIsoDate, unmappedInspectionReasons, unverifySite, unwrapResult, urlMatchKey, verificationMethodsFor, verifySite };

package/dist/query/index.d.mts

@@ -169,7 +169,7 @@ declare const impressions: MetricColumn<"impressions">;
 declare const ctr: MetricColumn<"ctr">;
 declare const position: MetricColumn<"position">;
 declare const searchType: QueryParam<"searchType">;
-type QueryErrorKind = 'missing-date-range' | 'invalid-row-limit' | 'invalid-start-row' | 'invalid-data-state' | 'invalid-aggregation-type' | 'invalid-builder-state' | 'unsupported-capability' | 'unresolvable-dataset';
+type QueryErrorKind = 'missing-date-range' | 'invalid-row-limit' | 'invalid-start-row' | 'invalid-data-state' | 'invalid-aggregation-type' | 'invalid-builder-state' | 'invalid-filter' | 'unsupported-capability' | 'unresolvable-dataset';
 type QueryError = {
   kind: 'missing-date-range';
   message: string;
@@ -191,6 +191,9 @@ type QueryError = {
   kind: 'invalid-builder-state';
   message: string;
   cause?: unknown;
+} | {
+  kind: 'invalid-filter';
+  message: string;
 } | {
   kind: 'unsupported-capability';
   capability: string;
@@ -214,12 +217,11 @@ declare const queryErrors: {
   readonly byNewsShowcaseNotAllowedWithPage: () => QueryError;
   readonly byNewsShowcaseRequiresShowcaseFilter: () => QueryError;
   readonly invalidBuilderState: (cause?: unknown) => QueryError;
+  readonly malformedFilterLeaf: () => QueryError;
   readonly unsupportedCapability: (capability: string, context: string) => QueryError;
   readonly unresolvableDataset: (dimensions: readonly Dimension[], filterDims?: readonly Dimension[]) => QueryError;
 };
 declare function isQueryError(value: unknown): value is QueryError;
-/** The human-readable rendering of a `QueryError`, for logs and string sinks. */
-declare function formatQueryError(error: QueryError): string;
 /**
  * Thrown when a query needs a planner capability (regex pushdown, comparison
  * joins, multi-dataset reads) the target engine lacks. Engines catch it to fall
@@ -353,14 +355,15 @@ declare function buildLogicalPlan(state: BuilderState, capabilities?: PlannerCap
  */
 declare function buildLogicalComparisonPlanResult(current: BuilderState, previous: BuilderState, capabilities?: PlannerCapabilities, comparisonFilter?: ComparisonFilter): Result<LogicalComparisonPlan, QueryError>;
 declare function buildLogicalComparisonPlan(current: BuilderState, previous: BuilderState, capabilities?: PlannerCapabilities, comparisonFilter?: ComparisonFilter): LogicalComparisonPlan;
-declare function isJsonFilter(value: unknown): value is JsonFilter;
-declare function parseJsonFilter(json: JsonFilter): Filter<any>;
 declare function normalizeFilter(input?: FilterInput): Filter<any> | undefined;
 /**
  * Errors-as-values core for {@link normalizeBuilderState}: returns an
  * `invalid-builder-state` `QueryError` when the untrusted partner-API body is
- * not an object, instead of throwing. Receive-edge parse, so hosts can map a bad
- * body to a 4xx.
+ * not an object, and an `invalid-filter` `QueryError` when a filter leaf lacks
+ * its string `dimension`/`operator`, instead of throwing. Also coerces
+ * alternative `orderBy` shapes into the canonical `{ column, dir }`.
+ * Receive-edge parse (parse, don't validate), so hosts can map a bad body to a
+ * 4xx and downstream consumers only ever see the canonical shape.
  */
 declare function normalizeBuilderStateResult(state: unknown): Result<BuilderState, QueryError>;
 declare function normalizeBuilderState(state: unknown): BuilderState;
@@ -389,4 +392,4 @@ declare function resolveToBody(state: BuilderState): GscSearchAnalyticsRequest;
 declare function currentPstDate(): string;
 declare function today(): string;
 declare function daysAgo(n: number): string;
-export { type BuilderState, type Column, type ComparisonFilter, Countries, type Country, type Device, Devices, type Dimension, type DimensionValueMap, type Filter, type FilterInput, type GSCQueryBuilder, type GSCResult, type GSCRow, type InternalFilter, type JsonFilter, type JsonInternalFilter, type LogicalComparisonPlan, type LogicalDataset, type LogicalDimensionFilter, type LogicalMetricFilter, type LogicalQueryPlan, type Metric, type MetricColumn, type PlannerCapabilities, QueryError, QueryErrorKind, type QueryParam, type QueryParamName, type QueryParamValueMap, type SearchType, SearchTypes, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, and, between, buildLogicalComparisonPlan, buildLogicalComparisonPlanResult, buildLogicalPlan, buildLogicalPlanResult, clicks, contains, country, ctr, currentPstDate, date, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, formatQueryError, gsc, gt, gte, hour, impressions, inArray, isJsonFilter, isQueryError, like, lt, lte, ne, normalizeBuilderState, normalizeBuilderStateResult, normalizeFilter, not, notRegex, or, page, parseJsonFilter, position, query, queryCanonical, queryErrorToException, queryErrors, regex, resolveToBody, resolveToBodyResult, searchAppearance, searchType, today, topLevel };
+export { type BuilderState, type Column, type ComparisonFilter, Countries, type Country, type Device, Devices, type Dimension, type DimensionValueMap, type Filter, type FilterInput, type GSCQueryBuilder, type GSCResult, type GSCRow, type InternalFilter, type JsonFilter, type JsonInternalFilter, type LogicalComparisonPlan, type LogicalDataset, type LogicalDimensionFilter, type LogicalMetricFilter, type LogicalQueryPlan, type Metric, type MetricColumn, type PlannerCapabilities, QueryError, QueryErrorKind, type QueryParam, type QueryParamName, type QueryParamValueMap, type SearchType, SearchTypes, UnresolvableDatasetError, UnsupportedLogicalCapabilityError, and, between, buildLogicalComparisonPlan, buildLogicalComparisonPlanResult, buildLogicalPlan, buildLogicalPlanResult, clicks, contains, country, ctr, currentPstDate, date, daysAgo, device, eq, extractDateRange, extractMetricFilters, extractSearchType, extractSpecialOperatorFilters, gsc, gt, gte, hour, impressions, inArray, isQueryError, like, lt, lte, ne, normalizeBuilderState, normalizeBuilderStateResult, normalizeFilter, not, notRegex, or, page, position, query, queryCanonical, queryErrorToException, queryErrors, regex, resolveToBody, resolveToBodyResult, searchAppearance, searchType, today, topLevel };