gscdump 1.3.2 → 1.4.1

package/dist/core/errors.mjs

@@ -0,0 +1,207 @@
+function pickField(error, paths, is) {
+	if (!error || typeof error !== "object") return void 0;
+	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;
+	}
+}
+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") 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;
+	}
+}
+const QUOTA_MESSAGE_RE = /quota|rate\s*limit/i;
+const QUOTA_REASONS = /* @__PURE__ */ new Set([
+	"dailyLimitExceeded",
+	"dailyLimitExceededUnreg",
+	"rateLimitExceeded",
+	"rateLimitExceededUnreg",
+	"userRateLimitExceeded",
+	"userRateLimitExceededUnreg",
+	"quotaExceeded",
+	"concurrentLimitExceeded",
+	"variableTermLimitExceeded",
+	"variableTermExpiredDailyExceeded",
+	"servingLimitExceeded",
+	"responseTooLarge",
+	"limitExceeded",
+	"batchSizeTooLarge",
+	"RATE_LIMIT_EXCEEDED",
+	"RESOURCE_EXHAUSTED"
+]);
+function extractReason(cause) {
+	const data = pickField(cause, [["data"]], (_v) => true);
+	if (data) {
+		const errorInfo = pickField(data, [["error", "details"]], (v) => Array.isArray(v));
+		if (errorInfo) {
+			const reason = errorInfo.find((d) => typeof d["@type"] === "string" && d["@type"].includes("ErrorInfo"))?.reason;
+			if (typeof reason === "string") return reason;
+		}
+		const directErrors = pickField(data, [["error", "errors"]], (v) => Array.isArray(v));
+		if (directErrors) {
+			const reason = directErrors[0]?.reason;
+			if (typeof reason === "string") return reason;
+		}
+	}
+}
+function isQuotaCondition(cause, message) {
+	const reason = extractReason(cause);
+	if (reason && QUOTA_REASONS.has(reason)) return true;
+	return QUOTA_MESSAGE_RE.test(message);
+}
+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 (isQuotaCondition(cause, message)) return {
+			kind: "rate-limited",
+			message,
+			retryAfter: extractRetryAfter(cause),
+			cause
+		};
+		return {
+			kind: "auth-expired",
+			message,
+			cause
+		};
+	}
+	if (status === 404 || status === 410) return {
+		kind: "not-found",
+		message,
+		cause
+	};
+	if (status === 400 || status === 402 || status === 409 || status === 413 || status === 422) return {
+		kind: "validation",
+		message,
+		cause
+	};
+	return {
+		kind: "transport",
+		message,
+		status,
+		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 {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		if (!(error instanceof SyntaxError)) throw error;
+	}
+	if (!parsed || !("error" in parsed)) return {
+		code: httpStatus ?? 500,
+		message: text || "Unknown Google API error"
+	};
+	if (typeof parsed.error === "string") {
+		const oauth = parsed;
+		return {
+			code: httpStatus ?? 400,
+			message: oauth.error_description || oauth.error,
+			reason: oauth.error
+		};
+	}
+	const err = parsed.error;
+	const errorInfo = err.details?.find((d) => d["@type"]?.includes("ErrorInfo"));
+	return {
+		code: err.code ?? httpStatus ?? 500,
+		message: err.message || err.status || text || `HTTP ${httpStatus ?? "?"}`,
+		reason: errorInfo?.reason,
+		status: err.status
+	};
+}
+var GscApiError = class extends Error {
+	info;
+	constructor(message, info) {
+		super(message);
+		this.info = info;
+		this.name = "GscApiError";
+	}
+};
+function rethrowAsGscApiError(prefix) {
+	return (err) => {
+		if (err instanceof GscApiError) throw err;
+		const maybe = err;
+		if (maybe && maybe.name === "FetchError") {
+			const info = parseGoogleError(typeof maybe.data === "string" ? maybe.data : JSON.stringify(maybe.data ?? {}), maybe.statusCode);
+			throw new GscApiError(`${prefix}: ${info.message}`, info);
+		}
+		throw err;
+	};
+}
+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));
+}
+export { GscApiError, classifyError, gscErrorToException, isPermissionDeniedError, parseGoogleError, rethrowAsGscApiError };

package/dist/core/indexing-issues.d.mts

@@ -0,0 +1,60 @@
+declare const INDEXING_ISSUE_FILTERS: {
+  readonly canonical_mismatch: `user_canonical IS NOT NULL AND google_canonical IS NOT NULL AND user_canonical != google_canonical`;
+  readonly stale_crawl: `last_crawl_time < datetime('now', '-30 days')`;
+  readonly very_stale_crawl: `last_crawl_time < datetime('now', '-60 days')`;
+  readonly not_indexed: `verdict IN ('FAIL', 'PARTIAL', 'NEUTRAL')`;
+  readonly unknown_to_google: `coverage_state = 'URL is unknown to Google'`;
+  readonly crawled_not_indexed: `coverage_state = 'Crawled - currently not indexed'`;
+  readonly discovered_not_indexed: `coverage_state = 'Discovered - currently not indexed'`;
+  readonly not_found: `page_fetch_state = 'NOT_FOUND' OR coverage_state = 'Not found (404)'`;
+  readonly soft_404: `page_fetch_state = 'SOFT_404' OR coverage_state = 'Soft 404'`;
+  readonly server_error: `page_fetch_state = 'SERVER_ERROR' OR coverage_state = 'Server error (5xx)'`;
+  readonly access_forbidden: `page_fetch_state = 'ACCESS_FORBIDDEN' OR coverage_state = 'Blocked due to access forbidden (403)'`;
+  readonly access_denied: `page_fetch_state = 'ACCESS_DENIED' OR coverage_state = 'Blocked due to unauthorized request (401)'`;
+  readonly blocked_4xx: `page_fetch_state = 'BLOCKED_4XX' OR coverage_state = 'Blocked due to other 4xx issue'`;
+  readonly redirect_error: `page_fetch_state = 'REDIRECT_ERROR' OR coverage_state = 'Redirect error'`;
+  readonly crawl_error: `page_fetch_state IN ('INTERNAL_CRAWL_ERROR', 'INVALID_URL')`;
+  readonly blocked_robots: `robots_txt_state = 'DISALLOWED'`;
+  readonly noindex: `indexing_state LIKE '%noindex%' OR coverage_state LIKE '%noindex%'`;
+  readonly redirect: `coverage_state = 'Page with redirect'`;
+  readonly sitemap_redirect: `coverage_state = 'Page with redirect' AND sitemaps IS NOT NULL AND sitemaps != '[]'`;
+  readonly alternate_canonical: `coverage_state = 'Alternate page with proper canonical tag'`;
+  readonly duplicate_no_canonical: `coverage_state = 'Duplicate without user-selected canonical'`;
+  readonly page_removed: `coverage_state = 'Blocked by page removal tool'`;
+  readonly fragment_url: `url LIKE '%#%'`;
+  readonly mobile_fail: `mobile_verdict IN ('FAIL', 'PARTIAL')`;
+  readonly rich_results_fail: `rich_results_verdict = 'FAIL'`;
+  readonly rich_results_warning: `rich_results_verdict = 'PARTIAL'`;
+  readonly rich_results_pass: `rich_results_verdict = 'PASS'`;
+};
+type IndexingIssueType = keyof typeof INDEXING_ISSUE_FILTERS;
+declare const INDEXING_ISSUE_LABELS: Record<IndexingIssueType, string>;
+declare const INDEXING_ISSUE_SEVERITY: Record<IndexingIssueType, 'error' | 'warning' | 'info'>;
+/**
+ * Every `pageFetchState` the URL Inspection API documents. `SUCCESSFUL` and the
+ * `_UNSPECIFIED` sentinel are non-faults; the rest each map to a filter above.
+ */
+declare const KNOWN_PAGE_FETCH_STATES: ReadonlySet<string>;
+/**
+ * Every `coverageState` string we have a bucket for, plus the indexed-state strings
+ * that are not faults. Google is free to invent new prose here at any time — that's
+ * exactly what {@link unmappedInspectionReasons} exists to catch.
+ */
+declare const KNOWN_COVERAGE_STATES: ReadonlySet<string>;
+interface UnmappedInspectionReasons {
+  coverageStates: string[];
+  pageFetchStates: string[];
+}
+/**
+ * Which reason strings in this batch of inspection results we have no bucket for.
+ *
+ * Pure, allocation-cheap, and safe to call on every ingest batch. A non-empty
+ * result means Google reports a state the filter map cannot see — the URLs are
+ * still counted in `not_indexed`, but nothing narrower, so the product will
+ * under-report exactly the way it did for `ACCESS_FORBIDDEN` before this existed.
+ */
+declare function unmappedInspectionReasons(rows: ReadonlyArray<{
+  coverageState?: string | null;
+  pageFetchState?: string | null;
+}>): UnmappedInspectionReasons;
+export { INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, IndexingIssueType, KNOWN_COVERAGE_STATES, KNOWN_PAGE_FETCH_STATES, UnmappedInspectionReasons, unmappedInspectionReasons };

package/dist/core/indexing-issues.mjs

@@ -0,0 +1,139 @@
+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 = 'Crawled - currently not indexed'`,
+	discovered_not_indexed: `coverage_state = 'Discovered - currently not indexed'`,
+	not_found: `page_fetch_state = 'NOT_FOUND' OR coverage_state = 'Not found (404)'`,
+	soft_404: `page_fetch_state = 'SOFT_404' OR coverage_state = 'Soft 404'`,
+	server_error: `page_fetch_state = 'SERVER_ERROR' OR coverage_state = 'Server error (5xx)'`,
+	access_forbidden: `page_fetch_state = 'ACCESS_FORBIDDEN' OR coverage_state = 'Blocked due to access forbidden (403)'`,
+	access_denied: `page_fetch_state = 'ACCESS_DENIED' OR coverage_state = 'Blocked due to unauthorized request (401)'`,
+	blocked_4xx: `page_fetch_state = 'BLOCKED_4XX' OR coverage_state = 'Blocked due to other 4xx issue'`,
+	redirect_error: `page_fetch_state = 'REDIRECT_ERROR' OR coverage_state = 'Redirect error'`,
+	crawl_error: `page_fetch_state IN ('INTERNAL_CRAWL_ERROR', 'INVALID_URL')`,
+	blocked_robots: `robots_txt_state = 'DISALLOWED'`,
+	noindex: `indexing_state LIKE '%noindex%' OR coverage_state LIKE '%noindex%'`,
+	redirect: `coverage_state = 'Page with redirect'`,
+	sitemap_redirect: `coverage_state = 'Page with redirect' AND sitemaps IS NOT NULL AND sitemaps != '[]'`,
+	alternate_canonical: `coverage_state = 'Alternate page with proper canonical tag'`,
+	duplicate_no_canonical: `coverage_state = 'Duplicate without user-selected canonical'`,
+	page_removed: `coverage_state = 'Blocked by page removal tool'`,
+	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",
+	discovered_not_indexed: "Discovered but not indexed",
+	not_found: "404 Not Found",
+	soft_404: "Soft 404",
+	server_error: "Server error",
+	access_forbidden: "Blocked: forbidden (403)",
+	access_denied: "Blocked: unauthorized (401)",
+	blocked_4xx: "Blocked: other 4xx",
+	redirect_error: "Redirect error",
+	crawl_error: "Crawl error",
+	blocked_robots: "Blocked by robots.txt",
+	noindex: "Noindex tag",
+	redirect: "Redirect",
+	sitemap_redirect: "Sitemap URL redirects",
+	alternate_canonical: "Alternate page with canonical",
+	duplicate_no_canonical: "Duplicate, no canonical declared",
+	page_removed: "Removed via removal tool",
+	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",
+	discovered_not_indexed: "warning",
+	not_found: "error",
+	soft_404: "error",
+	server_error: "error",
+	access_forbidden: "error",
+	access_denied: "error",
+	blocked_4xx: "error",
+	redirect_error: "error",
+	crawl_error: "warning",
+	blocked_robots: "warning",
+	noindex: "info",
+	redirect: "info",
+	sitemap_redirect: "warning",
+	alternate_canonical: "info",
+	duplicate_no_canonical: "warning",
+	page_removed: "info",
+	fragment_url: "warning",
+	mobile_fail: "warning",
+	rich_results_fail: "error",
+	rich_results_warning: "warning",
+	rich_results_pass: "info"
+};
+const KNOWN_PAGE_FETCH_STATES = /* @__PURE__ */ new Set([
+	"PAGE_FETCH_STATE_UNSPECIFIED",
+	"SUCCESSFUL",
+	"SOFT_404",
+	"BLOCKED_ROBOTS_TXT",
+	"NOT_FOUND",
+	"ACCESS_DENIED",
+	"SERVER_ERROR",
+	"REDIRECT_ERROR",
+	"ACCESS_FORBIDDEN",
+	"BLOCKED_4XX",
+	"INTERNAL_CRAWL_ERROR",
+	"INVALID_URL"
+]);
+const KNOWN_COVERAGE_STATES = /* @__PURE__ */ new Set([
+	"Submitted and indexed",
+	"Indexed, not submitted in sitemap",
+	"Indexed, though blocked by robots.txt",
+	"Indexed; consider marking as canonical",
+	"URL is unknown to Google",
+	"Crawled - currently not indexed",
+	"Discovered - currently not indexed",
+	"Not found (404)",
+	"Soft 404",
+	"Server error (5xx)",
+	"Blocked due to access forbidden (403)",
+	"Blocked due to unauthorized request (401)",
+	"Blocked due to other 4xx issue",
+	"Redirect error",
+	"Blocked by robots.txt",
+	"Excluded by ‘noindex’ tag",
+	"Page with redirect",
+	"Alternate page with proper canonical tag",
+	"Duplicate without user-selected canonical",
+	"Duplicate, Google chose different canonical than user",
+	"Blocked by page removal tool"
+]);
+function unmappedInspectionReasons(rows) {
+	const coverageStates = /* @__PURE__ */ new Set();
+	const pageFetchStates = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		const coverage = row.coverageState?.trim();
+		if (coverage && !KNOWN_COVERAGE_STATES.has(coverage)) coverageStates.add(coverage);
+		const fetchState = row.pageFetchState?.trim();
+		if (fetchState && !KNOWN_PAGE_FETCH_STATES.has(fetchState)) pageFetchStates.add(fetchState);
+	}
+	return {
+		coverageStates: [...coverageStates],
+		pageFetchStates: [...pageFetchStates]
+	};
+}
+export { INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, KNOWN_COVERAGE_STATES, KNOWN_PAGE_FETCH_STATES, unmappedInspectionReasons };

package/dist/core/property.d.mts

@@ -0,0 +1,41 @@
+interface GscPropertyCandidate {
+  siteUrl?: string | null;
+  permissionLevel?: string | null;
+}
+declare function isVerifiedGscProperty(property?: GscPropertyCandidate | null): boolean;
+declare function isVerifiedGscPermission(level: string | null | undefined): boolean;
+/**
+ * Does `propertyUrl` cover `targetDomain`? Matches sc-domain (exact or
+ * subdomain) and URL-prefix (host equality) without scheme/www noise.
+ */
+declare function gscPropertyMatchesTarget(targetDomain: string, propertyUrl: string | null | undefined): boolean;
+/**
+ * Convenience: match `siteUrl` against `gscSiteUrl` directly (extracts the
+ * hostname from `siteUrl` first).
+ */
+declare function matchGscSite(siteUrl: string | null | undefined, gscSiteUrl: string | null | undefined): boolean;
+/**
+ * Pick the best GSC property for a hostname from a candidate list. "Best":
+ *   1. Verified Domain property (widest + readable)
+ *   2. Verified URL-prefix property (narrower + readable)
+ *   3. Unverified Domain property (returned as a fallback so callers can
+ *      surface the verification gap to the user)
+ *   4. Unverified URL-prefix property (same caveat)
+ *
+ * Without this ranking, naively picking the first match would register an
+ * unverified property and leave the site stuck with zero data.
+ */
+declare function pickBestGscProperty<T extends GscPropertyCandidate>(origin: string, availableSites: readonly T[]): T | undefined;
+/**
+ * Richer best-property selection that also returns the matched domain and
+ * URL candidates separately, so callers can show "we matched on X domain
+ * property and Y URL-prefix property" diagnostics.
+ */
+declare function findBestGscProperty<T extends GscPropertyCandidate>(targetDomain: string, properties: readonly T[]): {
+  matchedSite: T | null;
+  domainProperty: T | null;
+  urlProperty: T | null;
+};
+declare function findExactGscProperty<T extends GscPropertyCandidate>(propertyUrl: string, properties: readonly T[]): T | null;
+declare function formatGscPropertyCandidates(candidates: ReadonlyArray<GscPropertyCandidate | null | undefined>): string;
+export { GscPropertyCandidate, findBestGscProperty, findExactGscProperty, formatGscPropertyCandidates, gscPropertyMatchesTarget, isVerifiedGscPermission, isVerifiedGscProperty, matchGscSite, pickBestGscProperty };

package/dist/core/property.mjs

@@ -0,0 +1,74 @@
+import { parseGscSiteUrl } from "./site-url.mjs";
+const VERIFIED_PERMISSIONS = /* @__PURE__ */ new Set([
+	"siteOwner",
+	"siteFullUser",
+	"siteRestrictedUser"
+]);
+function isVerifiedGscProperty(property) {
+	return !!property?.permissionLevel && VERIFIED_PERMISSIONS.has(property.permissionLevel);
+}
+function isVerifiedGscPermission(level) {
+	return !!level && VERIFIED_PERMISSIONS.has(level);
+}
+const stripWww = (d) => d.replace(/^www\./, "");
+function gscPropertyMatchesTarget(targetDomain, propertyUrl) {
+	if (!propertyUrl) return false;
+	const cleanTarget = stripWww(targetDomain);
+	const parsed = parseGscSiteUrl(propertyUrl);
+	if (parsed.isDomain) return cleanTarget === parsed.hostname || cleanTarget.endsWith(`.${parsed.hostname}`);
+	const match = propertyUrl.match(/^https?:\/\/([^/]+)/);
+	return !!match && stripWww(match[1].toLowerCase()) === cleanTarget;
+}
+function matchGscSite(siteUrl, gscSiteUrl) {
+	if (!siteUrl || !gscSiteUrl) return false;
+	const getHostname = (url) => {
+		if (url.startsWith("sc-domain:")) return url.replace("sc-domain:", "");
+		try {
+			return new URL(url).hostname;
+		} catch {
+			return url;
+		}
+	};
+	return gscPropertyMatchesTarget(getHostname(siteUrl), gscSiteUrl);
+}
+function pickBestGscProperty(origin, availableSites) {
+	const matches = availableSites.filter((p) => matchGscSite(origin, p.siteUrl));
+	if (!matches.length) return void 0;
+	const isDomain = (p) => !!p.siteUrl?.startsWith("sc-domain:");
+	const isHttps = (p) => !!p.siteUrl?.startsWith("https://");
+	const pickTier = (pool) => pool.find(isDomain) ?? pool.find(isHttps) ?? pool[0];
+	const verified = matches.filter((p) => isVerifiedGscPermission(p.permissionLevel));
+	const pool = verified.length ? verified : matches;
+	const originHost = stripWww(parseGscSiteUrl(origin).hostname.toLowerCase());
+	const exact = pool.filter((property) => {
+		if (!property.siteUrl) return false;
+		return stripWww(parseGscSiteUrl(property.siteUrl).hostname.toLowerCase()) === originHost;
+	});
+	return pickTier(exact.length ? exact : pool);
+}
+function findBestGscProperty(targetDomain, properties) {
+	const cleanTarget = stripWww(targetDomain);
+	const domainProperty = properties.find((property) => {
+		if (!property.siteUrl) return false;
+		const parsed = parseGscSiteUrl(property.siteUrl);
+		if (!parsed.isDomain) return false;
+		return cleanTarget === parsed.hostname || cleanTarget.endsWith(`.${parsed.hostname}`);
+	});
+	const urlProperty = properties.find((property) => {
+		if (!property.siteUrl) return false;
+		const match = property.siteUrl.match(/^https?:\/\/([^/]+)/);
+		return match && stripWww(match[1].toLowerCase()) === cleanTarget;
+	});
+	return {
+		matchedSite: (isVerifiedGscProperty(domainProperty) ? domainProperty : isVerifiedGscProperty(urlProperty) ? urlProperty : domainProperty || urlProperty) ?? null,
+		domainProperty: domainProperty ?? null,
+		urlProperty: urlProperty ?? null
+	};
+}
+function findExactGscProperty(propertyUrl, properties) {
+	return properties.find((property) => property.siteUrl === propertyUrl) ?? null;
+}
+function formatGscPropertyCandidates(candidates) {
+	return candidates.filter((c) => !!c).map((property) => `${property.siteUrl} (${property.permissionLevel})`).join(", ");
+}
+export { findBestGscProperty, findExactGscProperty, formatGscPropertyCandidates, gscPropertyMatchesTarget, isVerifiedGscPermission, isVerifiedGscProperty, matchGscSite, pickBestGscProperty };

package/dist/core/quota.d.mts

@@ -0,0 +1,2 @@
+declare const URL_INSPECTION_EFFECTIVE_LIMIT = 1800;
+export { URL_INSPECTION_EFFECTIVE_LIMIT };

package/dist/core/quota.mjs

@@ -0,0 +1,2 @@
+const URL_INSPECTION_EFFECTIVE_LIMIT = 1800;
+export { URL_INSPECTION_EFFECTIVE_LIMIT };

package/dist/core/result.d.mts

@@ -1,2 +1,20 @@
-import { Err, Ok, Result, err, isErr, isOk, ok, unwrapResult } from "../_chunks/result.mjs";
+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>;
+/**
+ * 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, ok, unwrapResult };

package/dist/core/scope-values.d.mts

@@ -0,0 +1,7 @@
+type GoogleScopesInput = string | readonly string[] | null | undefined;
+declare const GSC_READ_SCOPE: 'https://www.googleapis.com/auth/webmasters.readonly';
+declare const GSC_WRITE_SCOPE: 'https://www.googleapis.com/auth/webmasters';
+declare const GSC_INDEXING_SCOPE: 'https://www.googleapis.com/auth/indexing';
+declare const GSC_SITE_VERIFICATION_SCOPE: 'https://www.googleapis.com/auth/siteverification';
+declare function hasGoogleScope(scopes: GoogleScopesInput, scope: string): boolean;
+export { GSC_INDEXING_SCOPE, GSC_READ_SCOPE, GSC_SITE_VERIFICATION_SCOPE, GSC_WRITE_SCOPE, hasGoogleScope };

package/dist/core/scope-values.mjs

@@ -0,0 +1,15 @@
+const GSC_READ_SCOPE = "https://www.googleapis.com/auth/webmasters.readonly";
+const GSC_WRITE_SCOPE = "https://www.googleapis.com/auth/webmasters";
+const GSC_INDEXING_SCOPE = "https://www.googleapis.com/auth/indexing";
+const GSC_SITE_VERIFICATION_SCOPE = "https://www.googleapis.com/auth/siteverification";
+function parseGoogleScopes(scopes) {
+	if (!scopes) return [];
+	if (typeof scopes === "string") return scopes.split(/\s+/).map((scope) => scope.trim()).filter(Boolean);
+	return scopes.map((scope) => scope.trim()).filter(Boolean);
+}
+function hasGoogleScope(scopes, scope) {
+	const tokens = parseGoogleScopes(scopes);
+	const suffix = scope.replace("https://www.googleapis.com/auth/", "");
+	return tokens.includes(scope) || tokens.includes(suffix);
+}
+export { GSC_INDEXING_SCOPE, GSC_READ_SCOPE, GSC_SITE_VERIFICATION_SCOPE, GSC_WRITE_SCOPE, hasGoogleScope };

package/dist/core/scopes.d.mts

@@ -0,0 +1,5 @@
+type GoogleScopesInput = string | readonly string[] | null | undefined;
+declare function hasGscReadScope(scopes: GoogleScopesInput): boolean;
+declare function hasGscWriteScope(scopes: GoogleScopesInput): boolean;
+declare function hasIndexingScope(scopes: GoogleScopesInput): boolean;
+export { hasGscReadScope, hasGscWriteScope, hasIndexingScope };

package/dist/core/scopes.mjs

@@ -0,0 +1,11 @@
+import { GSC_INDEXING_SCOPE, GSC_WRITE_SCOPE, hasGoogleScope } from "./scope-values.mjs";
+function hasGscReadScope(scopes) {
+	return hasGoogleScope(scopes, "https://www.googleapis.com/auth/webmasters.readonly") || hasGoogleScope(scopes, "https://www.googleapis.com/auth/webmasters");
+}
+function hasGscWriteScope(scopes) {
+	return hasGoogleScope(scopes, GSC_WRITE_SCOPE);
+}
+function hasIndexingScope(scopes) {
+	return hasGoogleScope(scopes, GSC_INDEXING_SCOPE);
+}
+export { hasGscReadScope, hasGscWriteScope, hasIndexingScope };

package/dist/core/site-url.d.mts

@@ -0,0 +1,25 @@
+interface ParsedGscSiteUrl {
+  /** Original, canonical GSC property URL. */
+  label: string;
+  /** Bare hostname, stripped of protocol / sc-domain prefix / path. */
+  hostname: string;
+  /** Human-friendly label: scheme stripped, trailing slash trimmed, path retained. */
+  displayLabel: string;
+  propertyType: 'domain' | 'url-prefix';
+  isDomain: boolean;
+}
+declare function parseGscSiteUrl(siteUrl: string): ParsedGscSiteUrl;
+/**
+ * Comparison-canonical form of a GSC property URL. Strips `sc-domain:`,
+ * protocol, leading `www.`, trailing slash, and lowercases. Use when matching
+ * the same logical site across `https://www.example.com/` vs
+ * `sc-domain:example.com` vs bare hostnames — properties Google sometimes
+ * returns in different shapes for the same site.
+ */
+declare function normalizeGscSiteUrl(siteUrl: string): string;
+/**
+ * Normalize a user-input URL/hostname into a canonical registration target.
+ * Returns lowercase hostname stripped of protocol, or null if unparseable.
+ */
+declare function normalizeRegistrationTarget(inputUrl: string): string | null;
+export { ParsedGscSiteUrl, normalizeGscSiteUrl, normalizeRegistrationTarget, parseGscSiteUrl };

package/dist/core/site-url.mjs

@@ -0,0 +1,30 @@
+const SCHEME_RE = /^(sc-domain:|https?:\/\/)/;
+function parseGscSiteUrl(siteUrl) {
+	const isDomain = siteUrl.startsWith("sc-domain:");
+	let hostname = siteUrl;
+	if (isDomain) hostname = siteUrl.slice(10);
+	else try {
+		hostname = new URL(siteUrl).hostname;
+	} catch {
+		hostname = siteUrl;
+	}
+	const displayLabel = siteUrl.replace(SCHEME_RE, "").replace(/\/$/, "");
+	return {
+		label: siteUrl,
+		hostname,
+		displayLabel,
+		propertyType: isDomain ? "domain" : "url-prefix",
+		isDomain
+	};
+}
+function normalizeGscSiteUrl(siteUrl) {
+	return siteUrl.replace(/^sc-domain:/, "").replace(/^https?:\/\//, "").replace(/^www\./, "").replace(/\/$/, "").toLowerCase();
+}
+function normalizeRegistrationTarget(inputUrl) {
+	const trimmed = inputUrl.trim();
+	if (!trimmed) return null;
+	const inputParsed = parseGscSiteUrl(trimmed);
+	if (inputParsed.isDomain) return inputParsed.hostname.toLowerCase();
+	return trimmed.match(/^(?:https?:\/\/)?([^/]+)/)?.[1]?.toLowerCase() ?? null;
+}
+export { normalizeGscSiteUrl, normalizeRegistrationTarget, parseGscSiteUrl };