@gscdump/sdk 1.0.1 → 1.0.3

package/dist/indexing-issues.d.mts

@@ -0,0 +1,29 @@
+interface IndexingIssueDetail {
+  description: string;
+  fix: string;
+}
+type IssueSeverity = 'error' | 'warning' | 'info';
+interface IndexingIssue {
+  type: string;
+  label: string;
+  severity: IssueSeverity;
+  count: number;
+}
+declare const issueDetails: Record<string, IndexingIssueDetail>;
+declare const severityOrder: IssueSeverity[];
+interface IssueGroup {
+  id: string;
+  label: string;
+  icon: string;
+  description: string;
+  /** How hard are these to fix? Shown as a badge */
+  effort: 'quick' | 'moderate' | 'involved';
+  /** Does the user have direct control over these? */
+  controlLevel: 'full' | 'partial' | 'none';
+  /** Educational explanation shown in the group header */
+  education: string;
+  /** Issue types belonging to this group */
+  issueTypes: string[];
+}
+declare const issueGroups: IssueGroup[];
+export { IndexingIssue, IndexingIssueDetail, IssueGroup, IssueSeverity, issueDetails, issueGroups, severityOrder };

package/dist/indexing-issues.mjs

@@ -0,0 +1,168 @@
+const issueDetails = {
+	crawled_not_indexed: {
+		description: "Google crawled these pages but decided not to add them to the index. This often means the content was deemed low-quality, duplicate, or not useful enough.",
+		fix: "Improve content quality and uniqueness. Add internal links pointing to these pages. Ensure they have clear, distinct value compared to other pages on your site."
+	},
+	discovered_not_indexed: {
+		description: "Google knows these URLs exist but hasn't crawled them yet. This is usually a crawl-budget or priority signal — Google deemed other pages more important.",
+		fix: "Add strong internal links from indexed pages. Submit the URL via Search Console's URL Inspection > Request Indexing. Improve site authority and crawl-budget signals; check no resource constraints (slow server, large response sizes) are deterring the crawl."
+	},
+	server_error: {
+		description: "Google encountered 5xx server errors when trying to crawl these URLs. The pages were unreachable at crawl time.",
+		fix: "Check your server logs for errors. Ensure your hosting can handle Googlebot traffic. Fix any backend issues causing 500/502/503 errors."
+	},
+	access_forbidden: {
+		description: "Your server returned 403 Forbidden to Googlebot. Usually a WAF, bot-protection rule, or firewall treating the crawler as an attacker — a human visitor may see the page fine.",
+		fix: "Allowlist Googlebot in your WAF / bot-protection rules and verify by IP, not user agent. Check Cloudflare bot-fight mode, rate limits, and any geo or ASN blocking. Re-test with the URL Inspection tool's \"Test live URL\"."
+	},
+	access_denied: {
+		description: "Your server returned 401 Unauthorized to Googlebot. The URL sits behind an authentication wall.",
+		fix: "If the page should rank, remove the auth requirement for crawlers or move the content to a public URL. If it is genuinely private, block it in robots.txt or noindex it so it stops being reported as an indexing failure."
+	},
+	blocked_4xx: {
+		description: "Google got a 4xx response other than 401, 403, or 404 — commonly 410 Gone, 429 Too Many Requests, or 451.",
+		fix: "Check which status the URL actually returns. A 429 means Googlebot is being rate-limited: raise or exempt the crawler limit. A 410 is intentional deletion and will clear on its own."
+	},
+	redirect_error: {
+		description: "Google could not follow the redirect — a redirect chain that is too long, a loop, an empty Location header, or a URL that exceeds the maximum length.",
+		fix: "Collapse redirect chains to a single hop. Look for loops (A→B→A) and self-redirects. Point internal links and sitemap entries at the final destination URL."
+	},
+	crawl_error: {
+		description: "Google hit an internal crawl error or considered the URL malformed. Often transient on Google's side, but a persistent count means the URL itself is invalid.",
+		fix: "Verify the URL parses and resolves. Remove malformed URLs from your sitemap and internal links. If the URLs are valid, re-inspect in a few days — transient crawl errors clear themselves."
+	},
+	sitemap_redirect: {
+		description: "These URLs are submitted in your sitemap but redirect elsewhere. A sitemap should only list final, canonical, 200-status URLs — a redirecting entry wastes crawl budget and tells Google your sitemap is stale.",
+		fix: "Replace each redirecting entry with its destination URL, or drop it from the sitemap entirely. Then resubmit the sitemap."
+	},
+	alternate_canonical: {
+		description: "These pages declare a canonical pointing at another page, and Google honoured it. The canonical target is what gets indexed. Usually intentional.",
+		fix: "Nothing to fix if the canonical is deliberate. If these pages should rank on their own, make each one self-canonical and give it genuinely distinct content."
+	},
+	duplicate_no_canonical: {
+		description: "Google decided these pages duplicate another URL and picked the canonical itself, because the page declared no preference. You did not choose which URL ranks — Google did.",
+		fix: "Add a canonical link to every page. Point it at itself for pages that should rank, or at the preferred URL for genuine duplicates. Leaving it unset hands the decision to Google."
+	},
+	page_removed: {
+		description: "These URLs are suppressed by a request in Search Console's Removals tool. The block is temporary — roughly six months — and then they become eligible again.",
+		fix: "If the removal was intentional, back it with a real signal: a noindex tag, a 404/410, or authentication. The removal tool alone does not keep a page out of Search permanently."
+	},
+	unknown_to_google: {
+		description: "These URLs exist on your site but Google hasn't discovered them yet. They may be orphaned pages or missing from your sitemap.",
+		fix: "Add these URLs to your sitemap. Create internal links to them from well-indexed pages. Submit the sitemap in Google Search Console."
+	},
+	stale_crawl: {
+		description: "Google hasn't re-crawled these pages in over 30 days. They may have low perceived value or your crawl budget may be exhausted.",
+		fix: "Update content on these pages to signal freshness. Improve internal linking. Ensure your site loads quickly to maximize crawl budget efficiency."
+	},
+	very_stale_crawl: {
+		description: "Google hasn't visited these pages in over 60 days. They are at risk of being dropped from the index entirely.",
+		fix: "Prioritize updating these pages immediately. Add fresh internal links. Consider requesting re-indexing via Google Search Console's URL Inspection tool."
+	},
+	not_found: {
+		description: "These URLs return 404 errors. Google previously knew about them but they no longer exist.",
+		fix: "If the content moved, add 301 redirects to the new URLs. If intentionally removed, ensure no internal links still point to them. The 404s will clear over time."
+	},
+	soft_404: {
+		description: "These pages return a 200 status but Google detects them as effectively empty or error pages — \"soft\" 404s.",
+		fix: "Return a proper 404 status code for missing pages. If the pages should exist, add meaningful content. Avoid thin placeholder pages."
+	},
+	blocked_robots: {
+		description: "Your robots.txt file is preventing Google from crawling these URLs.",
+		fix: "Review your robots.txt rules. Remove Disallow directives for pages you want indexed. Remember that blocked pages can't be indexed even if linked."
+	},
+	noindex: {
+		description: "These pages have a noindex meta tag or X-Robots-Tag header, telling Google not to include them in search results.",
+		fix: "If these pages should be indexed, remove the noindex directive. Check for noindex in meta tags, HTTP headers, and any SEO plugin configuration."
+	},
+	redirect: {
+		description: "These URLs redirect to other pages. Google follows the redirect and indexes the destination instead.",
+		fix: "This is usually expected behavior. Ensure redirects point to the correct destination. Update internal links to point directly to the final URL to save crawl budget."
+	},
+	canonical_mismatch: {
+		description: "The canonical URL declared on these pages points to a different URL. Google may index the canonical target instead.",
+		fix: "Ensure each page's canonical tag points to itself, or intentionally to the preferred version. Fix any unintended canonical tags added by CMS plugins."
+	},
+	fragment_url: {
+		description: "These URLs contain fragment identifiers (#). Googlebot typically ignores fragments as they're client-side only.",
+		fix: "Avoid using fragment URLs as unique pages. If using client-side routing with hashes, migrate to proper URL paths for better indexability."
+	},
+	not_indexed: {
+		description: "These URLs are not in Google's index. This is a general category — the specific reason may vary.",
+		fix: "Check individual URLs in Google Search Console's URL Inspection tool for specific reasons. Common causes include quality, duplicate content, or crawl issues."
+	}
+};
+const severityOrder = [
+	"error",
+	"warning",
+	"info"
+];
+const issueGroups = [
+	{
+		id: "quick-wins",
+		label: "Quick Wins",
+		icon: "i-lucide-zap",
+		description: "Configuration changes you can make right now",
+		effort: "quick",
+		controlLevel: "full",
+		education: "These issues are caused by your site's configuration preventing Google from indexing certain pages. If these pages should be indexed, the fix is usually a one-line config change — remove a robots.txt rule, fix a canonical URL, or drop a redirecting entry from your sitemap. Highest-ROI fixes, zero content work.",
+		issueTypes: [
+			"blocked_robots",
+			"canonical_mismatch",
+			"duplicate_no_canonical",
+			"sitemap_redirect"
+		]
+	},
+	{
+		id: "technical",
+		label: "Technical Fixes",
+		icon: "i-lucide-wrench",
+		description: "Server and URL issues to resolve",
+		effort: "moderate",
+		controlLevel: "full",
+		education: "These are infrastructure problems — your server is returning errors, blocking Googlebot at the edge, failing to follow redirects, or serving pages that look empty. Fix crawl blocks and server errors first (they cost crawl budget and can drop indexed pages), then handle 404s with redirects.",
+		issueTypes: [
+			"server_error",
+			"not_found",
+			"soft_404",
+			"access_forbidden",
+			"access_denied",
+			"blocked_4xx",
+			"redirect_error",
+			"crawl_error"
+		]
+	},
+	{
+		id: "content-discovery",
+		label: "Content & Discovery",
+		icon: "i-lucide-file-search",
+		description: "Help Google find and value your pages",
+		effort: "involved",
+		controlLevel: "partial",
+		education: "Google found these pages but either didn't think they were worth indexing, or hasn't discovered them yet. For crawled-but-not-indexed pages, improving content quality and internal linking helps — but Google ultimately decides what to index. For undiscovered pages, adding them to your sitemap and linking to them from indexed pages is the fix.",
+		issueTypes: [
+			"crawled_not_indexed",
+			"discovered_not_indexed",
+			"unknown_to_google",
+			"stale_crawl",
+			"very_stale_crawl"
+		]
+	},
+	{
+		id: "expected",
+		label: "Expected Behavior",
+		icon: "i-lucide-info",
+		description: "Usually intentional — review but likely fine",
+		effort: "quick",
+		controlLevel: "none",
+		education: "These aren't really \"issues\" — they're usually intentional. Noindex tags are set deliberately to keep pages out of search. Redirects are normal when you move pages. An alternate page with a proper canonical is consolidation working as designed. Fragment URLs are stripped by Google. Review to make sure nothing unexpected is here.",
+		issueTypes: [
+			"noindex",
+			"redirect",
+			"alternate_canonical",
+			"page_removed",
+			"fragment_url"
+		]
+	}
+];
+export { issueDetails, issueGroups, severityOrder };

package/dist/lifecycle.d.mts

@@ -0,0 +1,14 @@
+import { GscdumpSyncStatusResponse, GscdumpUserSite, PartnerLifecycleSite } from "@gscdump/contracts";
+/**
+ * Stable lifecycle fields shared by the legacy partner response and public v1.
+ * Keeping the adapters structural lets consumers migrate to v1 without
+ * re-introducing legacy-only fields such as `intId` or `lifecycleRevision`.
+ */
+type LifecycleSiteLike = Pick<PartnerLifecycleSite, 'siteId' | 'externalSiteId' | 'requestedUrl' | 'gscPropertyUrl' | 'permissionLevel' | 'analytics' | 'indexing' | 'latestError' | 'updatedAt'>;
+declare function analyticsStatusToSyncStatus(status: LifecycleSiteLike['analytics']['status']): GscdumpUserSite['syncStatus'];
+declare function lifecycleSiteToUserSite(site: LifecycleSiteLike): GscdumpUserSite;
+declare function lifecycleSiteToSyncStatus(site: LifecycleSiteLike): GscdumpSyncStatusResponse;
+declare function findLifecycleSite<TSite extends LifecycleSiteLike>(lifecycle: {
+  sites: readonly TSite[];
+}, siteIdOrPropertyUrl: string): TSite | null;
+export { LifecycleSiteLike, analyticsStatusToSyncStatus, findLifecycleSite, lifecycleSiteToSyncStatus, lifecycleSiteToUserSite };

package/dist/lifecycle.mjs

@@ -0,0 +1,84 @@
+function normalizeLifecycleUrl(url) {
+	return (url || "").replace(/^sc-domain:/, "").replace(/^https?:\/\//, "").replace(/^www\./, "").replace(/\/$/, "").toLowerCase();
+}
+function normalizeGscPropertyKey(url) {
+	const value = url || "";
+	if (!value) return "";
+	if (value.startsWith("sc-domain:")) return `domain:${normalizeLifecycleUrl(value)}`;
+	if (!/^https?:\/\//.test(value)) return "";
+	return `url:${normalizeLifecycleUrl(value)}`;
+}
+function analyticsStatusToSyncStatus(status) {
+	switch (status) {
+		case "ready":
+		case "queryable_live":
+		case "queryable_partial": return "synced";
+		case "syncing":
+		case "preparing": return "syncing";
+		case "failed": return "error";
+		default: return "pending";
+	}
+}
+function lifecycleSiteToUserSite(site) {
+	const syncStatus = analyticsStatusToSyncStatus(site.analytics.status);
+	return {
+		siteId: site.siteId,
+		siteUrl: site.gscPropertyUrl || site.requestedUrl,
+		analyticsSyncStatus: syncStatus,
+		analyticsSyncProgress: site.analytics.progress,
+		syncStatus,
+		syncProgress: site.analytics.progress,
+		indexingEligible: site.indexing.eligible,
+		indexingIneligibleReason: site.indexing.reason,
+		indexingPermissionLevel: site.permissionLevel,
+		indexingStatus: site.indexing.status === "ready" ? "complete" : site.indexing.status === "not_requested" ? "not_started" : "indexing",
+		indexingProgress: site.indexing.progress,
+		lastSyncAt: site.updatedAt ? Date.parse(site.updatedAt) : null,
+		newestDateSynced: site.analytics.syncedRange.newest,
+		oldestDateSynced: site.analytics.syncedRange.oldest
+	};
+}
+function lifecycleSiteToSyncStatus(site) {
+	const syncStatus = analyticsStatusToSyncStatus(site.analytics.status);
+	const completed = site.analytics.progress.completed;
+	const failed = site.analytics.progress.failed;
+	const total = site.analytics.progress.total;
+	const queued = Math.max(total - completed - failed, 0);
+	return {
+		siteUrl: site.gscPropertyUrl || site.requestedUrl,
+		syncStatus,
+		oldestDateAvailable: site.analytics.syncedRange.oldest,
+		oldestDateSynced: site.analytics.syncedRange.oldest,
+		newestDateSynced: site.analytics.syncedRange.newest,
+		lastSyncAt: site.updatedAt ? Date.parse(site.updatedAt) : null,
+		lastError: site.latestError?.message ?? null,
+		jobs: {
+			queued,
+			processing: [
+				"queued",
+				"preparing",
+				"syncing"
+			].includes(site.analytics.status) ? 1 : 0,
+			completed,
+			failed
+		},
+		progress: site.analytics.progress.percent,
+		jobProgress: site.analytics.progress.percent,
+		daysSynced: completed,
+		daysAvailable: total,
+		isSyncing: [
+			"queued",
+			"preparing",
+			"syncing"
+		].includes(site.analytics.status),
+		hasData: site.analytics.queryable,
+		isComplete: site.analytics.queryable && site.analytics.status === "ready",
+		tables: {}
+	};
+}
+function findLifecycleSite(lifecycle, siteIdOrPropertyUrl) {
+	const normalized = normalizeLifecycleUrl(siteIdOrPropertyUrl);
+	const propertyKey = normalizeGscPropertyKey(siteIdOrPropertyUrl);
+	return lifecycle.sites.find((site) => site.siteId === siteIdOrPropertyUrl || site.externalSiteId === siteIdOrPropertyUrl || !!propertyKey && normalizeGscPropertyKey(site.gscPropertyUrl) === propertyKey || !site.gscPropertyUrl && normalizeLifecycleUrl(site.requestedUrl) === normalized || !propertyKey && normalizeLifecycleUrl(site.requestedUrl) === normalized) ?? null;
+}
+export { analyticsStatusToSyncStatus, findLifecycleSite, lifecycleSiteToSyncStatus, lifecycleSiteToUserSite };

package/dist/period.d.mts

@@ -0,0 +1,49 @@
+type RollingPeriod = '7d' | '28d' | '3m' | '6m' | '12m';
+type CalendarPeriod = 'this-week' | 'this-month' | 'last-month' | 'this-quarter' | 'this-year';
+/**
+ * Custom date range from drag-to-zoom.
+ *  - `custom:CS:CE` - current range only; prev range resolved by compareMode.
+ *  - `custom:CS:CE:PS:PE` - explicit prev range.
+ */
+type CustomPeriod = `custom:${string}:${string}` | `custom:${string}:${string}:${string}:${string}`;
+type Period = RollingPeriod | CalendarPeriod | CustomPeriod;
+type CompareMode = 'previous' | 'year' | 'none';
+interface DateRangeResult {
+  start: string;
+  end: string;
+  prevStart: string;
+  prevEnd: string;
+  yearStart: string;
+  yearEnd: string;
+  days: number;
+}
+interface PeriodOptions {
+  /** Subtract GSC's stable-data latency from `end`. Default `true`. */
+  stableData?: boolean;
+  /** IANA timezone used to resolve today's calendar date. Default GSC/Pacific time. */
+  timezone?: string;
+  /** Clock used to resolve today's calendar date. Defaults to the current time. */
+  now?: Date;
+}
+declare function isCustomPeriod(p: Period | string): p is CustomPeriod;
+declare function parseCustomPeriod(p: Period | string): {
+  start: string;
+  end: string;
+  prevStart?: string;
+  prevEnd?: string;
+} | null;
+declare function periodToDateRange(period: Period | string, stableDataOrOptions?: boolean | PeriodOptions): DateRangeResult;
+declare function periodToDays(period: Period | string, stableDataOrOptions?: boolean | PeriodOptions): number;
+declare function compareRange(range: DateRangeResult, mode: CompareMode): {
+  start: string;
+  end: string;
+} | null;
+/**
+ * GSC data within the last `GSC_STABLE_LATENCY_DAYS` (PST) is potentially
+ * incomplete. Returns the cutoff date (YYYY-MM-DD); compare row dates against
+ * this to dim/strike unstable points in charts.
+ *
+ * Uses YYYY-MM-DD string math directly to avoid UTC/local timezone shifts.
+ */
+declare function getGscUnstableCutoffDate(): string;
+export { CalendarPeriod, CompareMode, CustomPeriod, DateRangeResult, Period, PeriodOptions, RollingPeriod, compareRange, getGscUnstableCutoffDate, isCustomPeriod, parseCustomPeriod, periodToDateRange, periodToDays };

package/dist/period.mjs

@@ -0,0 +1,138 @@
+import "./gsc-constants.mjs";
+import { resolveWindow } from "@gscdump/engine/period";
+import { endOfMonth } from "date-fns/endOfMonth";
+import { format } from "date-fns/format";
+import { startOfMonth } from "date-fns/startOfMonth";
+import { startOfQuarter } from "date-fns/startOfQuarter";
+import { startOfWeek } from "date-fns/startOfWeek";
+import { subDays } from "date-fns/subDays";
+import { subMonths } from "date-fns/subMonths";
+function isCustomPeriod(p) {
+	return typeof p === "string" && p.startsWith("custom:");
+}
+function parseCustomPeriod(p) {
+	if (!isCustomPeriod(p)) return null;
+	const [, start, end, prevStart, prevEnd] = p.split(":");
+	if (!start || !end) return null;
+	if (prevStart && prevEnd) return {
+		start,
+		end,
+		prevStart,
+		prevEnd
+	};
+	return {
+		start,
+		end
+	};
+}
+function todayInTimezone(timezone = "America/Los_Angeles", now = /* @__PURE__ */ new Date()) {
+	const date = new Intl.DateTimeFormat("en-CA", {
+		timeZone: timezone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit"
+	}).format(now);
+	return /* @__PURE__ */ new Date(`${date}T00:00:00`);
+}
+const ROLLING_TO_UPSTREAM = {
+	"7d": "last-7d",
+	"28d": "last-28d",
+	"3m": "last-90d",
+	"6m": "last-180d",
+	"12m": "last-365d"
+};
+const CALENDAR_TO_UPSTREAM = {
+	"this-month": "mtd",
+	"this-year": "ytd"
+};
+function fmt(d) {
+	return format(d, "yyyy-MM-dd");
+}
+function buildResultFromIso(start, end) {
+	const startDate = /* @__PURE__ */ new Date(`${start}T00:00:00`);
+	const endDate = /* @__PURE__ */ new Date(`${end}T00:00:00`);
+	const days = Math.round((endDate.getTime() - startDate.getTime()) / 864e5) + 1;
+	const prev = resolveWindow({
+		preset: "custom",
+		start,
+		end,
+		comparison: "prev-period"
+	});
+	const yoy = resolveWindow({
+		preset: "custom",
+		start,
+		end,
+		comparison: "yoy"
+	});
+	return {
+		start,
+		end,
+		prevStart: prev.comparison.start,
+		prevEnd: prev.comparison.end,
+		yearStart: yoy.comparison.start,
+		yearEnd: yoy.comparison.end,
+		days
+	};
+}
+function periodToDateRange(period, stableDataOrOptions = true) {
+	const options = typeof stableDataOrOptions === "boolean" ? { stableData: stableDataOrOptions } : stableDataOrOptions;
+	const stableData = options.stableData ?? true;
+	const custom = parseCustomPeriod(period);
+	if (custom) {
+		const result = buildResultFromIso(custom.start, custom.end);
+		if (custom.prevStart && custom.prevEnd) return {
+			...result,
+			prevStart: custom.prevStart,
+			prevEnd: custom.prevEnd,
+			yearStart: custom.prevStart,
+			yearEnd: custom.prevEnd
+		};
+		return result;
+	}
+	const today = todayInTimezone(options.timezone, options.now);
+	const end = stableData ? subDays(today, 3) : subDays(today, 1);
+	const endIso = fmt(end);
+	const upstreamPreset = ROLLING_TO_UPSTREAM[period] ?? CALENDAR_TO_UPSTREAM[period];
+	if (upstreamPreset) {
+		const win = resolveWindow({
+			preset: upstreamPreset,
+			anchor: endIso
+		});
+		return buildResultFromIso(win.start, win.end);
+	}
+	let start;
+	switch (period) {
+		case "this-week":
+			start = startOfWeek(end, { weekStartsOn: 1 });
+			break;
+		case "last-month": {
+			const prevMonth = subMonths(end, 1);
+			return buildResultFromIso(fmt(startOfMonth(prevMonth)), fmt(endOfMonth(prevMonth)));
+		}
+		case "this-quarter":
+			start = startOfQuarter(end);
+			break;
+		default: start = subDays(end, 27);
+	}
+	return buildResultFromIso(fmt(start), endIso);
+}
+function periodToDays(period, stableDataOrOptions = true) {
+	return periodToDateRange(period, stableDataOrOptions).days;
+}
+function compareRange(range, mode) {
+	if (mode === "none") return null;
+	if (mode === "year") return {
+		start: range.yearStart,
+		end: range.yearEnd
+	};
+	return {
+		start: range.prevStart,
+		end: range.prevEnd
+	};
+}
+function getGscUnstableCutoffDate() {
+	const [y, m, d] = (/* @__PURE__ */ new Date()).toLocaleDateString("en-CA", { timeZone: "America/Los_Angeles" }).split("-").map(Number);
+	const cutoff = new Date(y, m - 1, d - 3);
+	return `${cutoff.getFullYear()}-${String(cutoff.getMonth() + 1).padStart(2, "0")}-${String(cutoff.getDate()).padStart(2, "0")}`;
+}
+export { compareRange, getGscUnstableCutoffDate, isCustomPeriod, parseCustomPeriod, periodToDateRange, periodToDays };

package/dist/search-console-stage.d.mts

@@ -0,0 +1,102 @@
+type SearchConsoleStageKey = 'not_connected' | 'waiting_for_data' | 'weak_discovery' | 'discovery_backlog' | 'crawl_blocked' | 'indexability_blocked' | 'index_rejection' | 'partially_indexed' | 'indexed_invisible' | 'visible_not_clicked' | 'ranking_stalled' | 'declining_visibility' | 'healthy_growth_ready';
+type SearchConsoleStageSeverity = 'success' | 'error' | 'warning' | 'info' | 'neutral';
+interface SearchConsoleStageEvidence {
+  label: string;
+  value: string;
+  source: 'connection' | 'indexing' | 'sitemap' | 'performance' | 'inspection' | 'canonical';
+}
+interface SearchConsoleStage {
+  key: SearchConsoleStageKey;
+  label: string;
+  severity: SearchConsoleStageSeverity;
+  summary: string;
+  primaryAction: string;
+  nextStage: SearchConsoleStageKey | null;
+  evidence: SearchConsoleStageEvidence[];
+  sprintFindingTypes: string[];
+}
+interface SearchConsoleStageIssue {
+  type: string;
+  label: string;
+  severity?: 'error' | 'warning' | 'info';
+  count: number;
+}
+interface SearchConsoleStageSummary {
+  totalUrls: number;
+  indexed: number;
+  indexedPercent: number;
+  change7d?: number | null;
+  change28d?: number | null;
+}
+/**
+ * Trajectory + maturity signals (v2). These are first-class axes: a site that
+ * is growing over the robust 90-day window is told to keep expanding, never to
+ * "fix indexing", regardless of coverage%. Percent fields are whole numbers
+ * (e.g. 42.6 for +42.6%); `positionDelta90d` is current − prior (negative =
+ * rank improved). Window contract: callers MUST drop the trailing ~3 GSC lag
+ * days before computing these, and the 7-day window is intentionally absent —
+ * it is too lag-contaminated to classify on.
+ */
+interface SearchConsoleStageTrajectory {
+  clicksPct90d?: number | null;
+  impressionsPct90d?: number | null;
+  positionDelta90d?: number | null;
+  clicksPct28d?: number | null;
+  /**
+   * Absolute clicks in the PRIOR 28-day window — the baseline a decline would
+   * be measured against. Gates decline detection so a percentage crash on
+   * trivial traffic (8 → 2 clicks) is not mistaken for a real loss.
+   */
+  clicksPrior28d?: number | null;
+}
+interface SearchConsoleStageSitemap {
+  errors?: number | null;
+  warnings?: number | null;
+  lastError?: string | null;
+  urlCount?: number | null;
+}
+interface SearchConsoleStagePage {
+  impressions: number;
+  clicks: number;
+  position?: number | null;
+}
+interface ClassifySearchConsoleStageInput {
+  connected: boolean;
+  indexingStatus?: 'pending' | 'partial' | 'complete' | 'unknown' | string | null;
+  summary?: SearchConsoleStageSummary | null;
+  issues?: SearchConsoleStageIssue[] | null;
+  sitemaps?: SearchConsoleStageSitemap[] | null;
+  canonicalMismatchCount?: number | null;
+  pageInventory?: SearchConsoleStagePage[] | null;
+  ctrOutlierCount?: number | null;
+  pageMoverDropCount?: number | null;
+  /** v2 trajectory axis — when present, drives the growth override + decline detection. */
+  trajectory?: SearchConsoleStageTrajectory | null;
+  /** v2 maturity axis — impressions over the trailing 28 days. Gates whether coverage% is even meaningful. */
+  impressions28d?: number | null;
+  /**
+   * v2 on-page technical faults from the crawl audit (broken links/images,
+   * server errors, access failures) — counted as hard blockers alongside GSC
+   * crawl reasons. Excludes intentional noindex.
+   */
+  crawlAuditBlockerCount?: number | null;
+  /** v2 authority signal — open recoverable broken backlinks (expansion lever, not a defect). */
+  recoverableBacklinkCount?: number | null;
+  /** v2 authority signal — cross-competitor content-gap topics (expansion readiness). */
+  competitorGapCount?: number | null;
+  /**
+   * v2 site purpose (AI profile `type`). Benchmarks the verdict against intent:
+   * informational types (docs/blog/portfolio) earn structurally low CTR, so the
+   * visible-not-clicked bar is raised for them. Unknown/null → `other`.
+   */
+  siteType?: string | null;
+}
+/**
+ * v2 classifier. Trajectory and maturity are first-class axes that run BEFORE
+ * the coverage/discovery rungs, so a growing site is told to keep expanding —
+ * never to "fix indexing". Reuses the existing stage-key enum (growth →
+ * `healthy_growth_ready`, nascent → `waiting_for_data`, mass crawled-not-indexed
+ * → `index_rejection`, on-page/crawl faults → `crawl_blocked`).
+ */
+declare function classifySearchConsoleStage(input: ClassifySearchConsoleStageInput): SearchConsoleStage;
+export { ClassifySearchConsoleStageInput, SearchConsoleStage, SearchConsoleStageEvidence, SearchConsoleStageIssue, SearchConsoleStageKey, SearchConsoleStagePage, SearchConsoleStageSeverity, SearchConsoleStageSitemap, SearchConsoleStageSummary, SearchConsoleStageTrajectory, classifySearchConsoleStage };