seo 0.4.0 → 0.4.1

package/dist/mcp.js

@@ -1,5 +1,5 @@
 import { createRequire as __seoCreateRequire } from 'node:module'; const require = __seoCreateRequire(import.meta.url);
-import { i as __toESM, n as load, r as __commonJSMin, t as version } from "./package-BfqlCbxN.js";
+import { i as __toESM, n as load, r as __commonJSMin, t as version } from "./package-CeYsRRpB.js";
 import { createHash, randomUUID, sign } from "node:crypto";
 import { ZodOptional, z } from "zod";
 import { chmodSync, createReadStream, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
@@ -19914,7 +19914,7 @@ const TOPIC_WORDS = /* @__PURE__ */ new Set([
 	"free",
 	"guide",
 	"how",
-	"inference",
+	"example",
 	"install",
 	"integration",
 	"local",
@@ -30733,12 +30733,13 @@ async function listSearchUpdates(input = {}) {
 /** The step-change heuristic and its thresholds, returned with the report. */
 const STEP_CHANGE_RULES = {
 	method: "best-split",
-	description: "Heuristic. The change date is the split of the daily series where the mean before and the mean after differ most, weighted by segment length. It counts as a step change only when it is sudden and sustained. Sudden: the median of up to localDays observed days after the date differs from the median of up to localDays days before it by at least minLocalShiftInStdDevs pooled within-segment standard deviations, so one unusual day is not a step and a slow trend is not a step. Sustained: the mean of every day from the date differs from the mean before it by a z-score of at least minZScore, stricter than the recent-window test because the date is chosen from the data. Otherwise the last recentDays are compared with the days before them.",
+	description: "Heuristic. The change date is the split of the daily series where the mean before and the mean after differ most, weighted by segment length. It counts as a step change only when it is sudden and sustained. Sudden: the median of up to localDays observed days after the date differs from the median of up to localDays days before it by at least minLocalShiftInStdDevs pooled within-segment standard deviations, so one unusual day is not a step and a slow trend is not a step. Sustained: the mean of every day from the date differs from the mean before it by a z-score of at least minZScore, stricter than the recent-window test because the date is chosen from the data. These tests use daily values capped at the capDays and 1 - capDays quantiles, so one spike day cannot hide a lasting step. Otherwise the last recentDays are compared with the days before them.",
 	minDaysBefore: 7,
 	minDaysAfter: 3,
 	localDays: 7,
 	minLocalShiftInStdDevs: 2,
-	minZScore: 3
+	minZScore: 3,
+	capDays: .05
 };
 /**
 * The dates to check against Google updates (before padding): the change
@@ -30914,10 +30915,18 @@ function sumOfSquaredDeviations(values) {
 	const average = mean(values);
 	return values.reduce((sum, value) => sum + (value - average) ** 2, 0);
 }
-function findStepChange(values) {
+function capped(values) {
+	const sorted = [...values].sort((a, b) => a - b);
+	const last = sorted.length - 1;
+	const low = sorted[Math.floor(last * STEP_CHANGE_RULES.capDays)] ?? 0;
+	const high = sorted[Math.ceil(last * (1 - STEP_CHANGE_RULES.capDays))] ?? 0;
+	return values.map((value) => Math.min(high, Math.max(low, value)));
+}
+function findStepChange(observed) {
 	const { minDaysBefore, minDaysAfter, localDays, minLocalShiftInStdDevs, minZScore } = STEP_CHANGE_RULES;
-	const count = values.length;
+	const count = observed.length;
 	if (count < minDaysBefore + minDaysAfter) return null;
+	const values = capped(observed);
 	const sums = [0];
 	for (const value of values) sums.push((sums.at(-1) ?? 0) + value);
 	const total = sums[count] ?? 0;
@@ -36213,7 +36222,7 @@ function bingSiteFor(sites, target) {
 	};
 	const wanted = host(target);
 	if (!wanted) return null;
-	return sites.filter((site) => site.verified && host(site.url) === wanted).sort((a, b) => Number(b.url.startsWith("https://")) - Number(a.url.startsWith("https://")) || a.url.localeCompare(b.url, "en"))[0]?.url ?? null;
+	return sites.filter((site) => host(site.url) === wanted).sort((a, b) => Number(b.verified) - Number(a.verified) || Number(b.url.startsWith("https://")) - Number(a.url.startsWith("https://")) || a.url.localeCompare(b.url, "en"))[0] ?? null;
 }
 //#endregion
 //#region packages/core/dist/commands/present.js
@@ -36789,6 +36798,8 @@ async function runAnalyticsRows(input, google, options) {
 const BING_LIMITS = ["Bing and Google count clicks, impressions and positions their own way. Their numbers sit side by side here and are never added together.", "Bing lists only its top queries and pages, grouped by week. A query or page missing from Bing’s list is unknown, not zero."];
 const LOCAL_BING = "Bing data runs on the person’s machine with the CLI: connect a Bing Webmaster API key once with `npx -y seo providers bing connect`, then run `npx -y seo report --site <site> --section bing --json`.";
 const NO_BING_HERE = "Bing: not included here, so these totals show Google only. Some sites get most of their search visits from Bing; run `npx -y seo report --site <site> --section bing --json` with the CLI to see them.";
+const BING_HOME = "https://www.bing.com/webmasters";
+const noBingData = (site) => `Bing has no data for ${site} yet. Newly added or newly verified sites take a few days to show data in Bing Webmaster Tools.`;
 const sitesSeen = /* @__PURE__ */ new WeakMap();
 async function bingFor(deps, property) {
 	if (!deps.bing) return {
@@ -36808,13 +36819,14 @@ async function bingFor(deps, property) {
 		sitesSeen.set(call, sites);
 	}
 	const site = bingSiteFor(await sites, property);
-	return site ? {
+	if (site?.verified) return {
 		call,
-		site
-	} : {
+		site: site.url
+	};
+	return {
 		call: null,
 		site: null,
-		missing: `The connected Bing account has no verified site for ${property.replace(/^sc-domain:/, "")}. Add it in Bing Webmaster Tools; it can import sites from Search Console.`
+		missing: site ? `${site.url} is in the connected Bing account but is not verified, so Bing gives no data for it. Verify it at ${BING_HOME}.` : `The connected Bing account does not have ${property.replace(/^sc-domain:/, "")}. Add and verify it at ${BING_HOME} (it can import sites from Search Console). New sites take a few days to show data.`
 	};
 }
 function days(range) {
@@ -36823,6 +36835,7 @@ function days(range) {
 async function bingTotals(source, range, before) {
 	if (!source.call) return { missing: source.missing };
 	const traffic = await bingTraffic(source.call, source.site);
+	if (!traffic.rows.length && !traffic.invalidRows) return { missing: noBingData(source.site) };
 	const sum = (window) => {
 		const rows = traffic.rows.filter((row) => row.date >= window.startDate && row.date <= window.endDate);
 		return {
@@ -36889,24 +36902,26 @@ async function bingSection(source, read, property, range) {
 		dataState: "final",
 		maxRows: 25e3
 	});
-	const [queries, pages, googleQueries, googlePages] = await Promise.all([
+	const [queries, pages, googleRead] = await Promise.all([
 		bingQueries(source.call, source.site),
 		bingPages(source.call, source.site),
-		google("query"),
-		google("page")
+		Promise.all([google("query"), google("page")]).catch((error) => error instanceof Error ? error : new Error(String(error)))
 	]);
+	const googleError = googleRead instanceof Error ? googleRead : null;
+	const [googleQueries, googlePages] = googleRead instanceof Error ? [] : googleRead;
 	const beside = (bing, googleRows, name) => {
 		const norm = (value) => name === "query" ? value.toLowerCase().trim() : value.replace(/#.*$/, "");
-		const byKey = new Map(googleRows.map((row) => [norm(row.keys[0] ?? ""), row]));
+		const byKey = new Map(googleRows?.map((row) => [norm(row.keys[0] ?? ""), row]));
 		return bing.map((row) => {
 			const g = byKey.get(norm(row.key));
+			const known = googleRows ? 0 : null;
 			return {
 				[name]: row.key,
 				bingClicks: row.clicks,
 				bingImpressions: row.impressions,
 				bingPosition: row.position,
-				googleClicks: g?.clicks ?? 0,
-				googleImpressions: g?.impressions ?? 0,
+				googleClicks: g?.clicks ?? known,
+				googleImpressions: g?.impressions ?? known,
 				googlePosition: g ? Math.round(g.position * 10) / 10 : null
 			};
 		});
@@ -36914,6 +36929,7 @@ async function bingSection(source, read, property, range) {
 	const q = sumWeeks(queries.rows, range);
 	const p = sumWeeks(pages.rows, range);
 	const invalid = queries.invalidRows + pages.invalidRows;
+	const empty = !queries.rows.length && !pages.rows.length && !invalid;
 	return {
 		range,
 		bingSite: source.site,
@@ -36922,9 +36938,11 @@ async function bingSection(source, read, property, range) {
 			bingPages: p.rows.length,
 			weeks: q.weeks.length
 		},
-		items: beside(q.rows, googleQueries.rows, "query"),
-		topPages: beside(p.rows, googlePages.rows, "page"),
+		items: beside(q.rows, googleQueries?.rows, "query"),
+		topPages: beside(p.rows, googlePages?.rows, "page"),
 		caveats: [
+			...empty ? [noBingData(source.site)] : [],
+			...googleError ? [`Search Console was not available, so the Google columns are empty (unknown, not zero): ${googleError.message}`] : [],
 			`Bing weeks counted: ${q.weeks.join(", ") || "none"} (each date names a week). Google numbers cover ${range.startDate} to ${range.endDate} exactly.`,
 			"Google numbers are for the same query text or page URL. 0 means Google showed no row for it in these dates.",
 			...BING_LIMITS,
@@ -36962,6 +36980,7 @@ async function runBingRows(input, deps) {
 		});
 	}
 	const notes = [
+		...all.rows.length || all.invalidRows ? [] : [noBingData(source.site)],
 		`Bing weeks counted: ${now.weeks.join(", ") || "none"}; earlier period ${then.weeks.join(", ") || "none"}. Each date names a week.`,
 		...BING_LIMITS.slice(1),
 		...all.invalidRows ? [`${all.invalidRows} Bing rows were not valid and were left out.`] : []
@@ -37172,6 +37191,11 @@ async function facts(url) {
 function checkPages(urls) {
 	return Promise.all(urls.slice(0, MAX_PAGES).map(facts));
 }
+function temporaryRedirectNote(pages) {
+	const temporary = pages.filter((page) => (page.status === 302 || page.status === 307) && page.redirects_to !== null && new URL(page.redirects_to).host === new URL(page.url).host);
+	if (!temporary.length) return null;
+	return `Note: 302 and 307 are temporary redirects; a permanent move usually uses 301 or 308. Temporary redirects here: ${temporary.map((page) => `${page.url} (${page.status} to ${page.redirects_to})`).join("; ")}.`;
+}
 //#endregion
 //#region packages/core/dist/commands/report.js
 const SECTIONS = {
@@ -37461,7 +37485,7 @@ function reportUrls(rows, origin) {
 	return found;
 }
 function pageFactsTable(checked, origin) {
-	return table(checked, [
+	const rows = table(checked, [
 		"url",
 		"status",
 		"redirects_to",
@@ -37472,6 +37496,8 @@ function pageFactsTable(checked, origin) {
 		"robots",
 		...checked.some((page) => page.error) ? ["error"] : []
 	], origin, 320);
+	const note = temporaryRedirectNote(checked);
+	return note ? `${rows}\n${note}` : rows;
 }
 const PAGE_SIZE = 50;
 async function allSections(input, deps) {
@@ -37788,11 +37814,48 @@ const RESEARCH_ACTIONS = [
 ];
 const RESEARCH_PROVIDERS = ["dataforseo", "ahrefs"];
 const RESEARCH_HELP = "keyword_metrics (keywords: volume, difficulty, CPC), ranked_keywords (target: keywords a domain or URL ranks for), serp (keywords, up to 5: the ranking pages), competitors (target: domains that share keywords), backlinks (target: referring domains). Rows with a domain, and the target, get a free Ahrefs domain_rating column. Numbers are provider estimates, not Search Console data.";
+const GENERIC_PLATFORMS = [
+	"youtube.com",
+	"facebook.com",
+	"wikipedia.org",
+	"reddit.com",
+	"quora.com",
+	"instagram.com",
+	"linkedin.com",
+	"x.com",
+	"twitter.com",
+	"pinterest.com",
+	"tiktok.com",
+	"amazon.com"
+];
+const within = (domain, parent) => domain === parent || domain.endsWith(`.${parent}`);
+function realCompetitors(rows, target) {
+	const self = bareDomain(target);
+	const domainOf = (row) => bareDomain(String(row.domain ?? row.competitor_domain ?? ""));
+	const isSelf = (domain) => self !== "" && within(domain, self);
+	const isPlatform = (domain) => GENERIC_PLATFORMS.some((name) => within(domain, name));
+	const domains = rows.map(domainOf);
+	const own = domains.filter(isSelf);
+	const platforms = domains.filter((d) => !isSelf(d) && isPlatform(d));
+	const gone = own.length + platforms.length;
+	if (!gone) return {
+		rows,
+		note: null
+	};
+	const reasons = [own.length ? `the target itself (${own.join(", ")})` : "", platforms.length ? `generic platforms that share keywords with most sites (${platforms.join(", ")})` : ""].filter(Boolean);
+	return {
+		rows: rows.filter((row) => {
+			const domain = domainOf(row);
+			return !isSelf(domain) && !isPlatform(domain);
+		}),
+		note: `Left out ${gone} ${gone === 1 ? "row" : "rows"}: ${reasons.join(" and ")}. The fixed platform list is ${GENERIC_PLATFORMS.join(", ")}.`
+	};
+}
 async function runResearch(input, keys, options) {
 	const country = input.country ?? "us";
 	const target = input.target ?? "";
 	const offset = input.offset ?? 0;
-	const rows = await research(input.provider, keys, {
+	const found = await research(input.provider, keys, {
 		action: input.action,
 		keywords: input.keywords ?? [],
 		target,
@@ -37800,6 +37863,10 @@ async function runResearch(input, keys, options) {
 		language: "en",
 		limit: Math.min(1e3, Math.max(100, offset + 50))
 	});
+	const { rows, note } = input.action === "competitors" ? realCompetitors(found, target) : {
+		rows: found,
+		note: null
+	};
 	const drKey = keys.get("x-ahrefs-key") ?? options.drKey;
 	const rated = await withDomainRating(rows, drKey);
 	const targetDr = target ? (await domainRatings([target], drKey)).get(bareDomain(target)) : void 0;
@@ -37813,6 +37880,7 @@ async function runResearch(input, keys, options) {
 			detail: input.detail ?? "summary",
 			notes: [
 				`${input.provider} estimates, in the provider’s own units.`,
+				...note ? [note] : [],
 				...hasTargetDr ? [`${bareDomain(target)} domain_rating: ${targetDr}.`] : [],
 				...rated.added || hasTargetDr ? [DR_ATTRIBUTION] : []
 			],
@@ -37825,6 +37893,7 @@ async function runResearch(input, keys, options) {
 			country,
 			targetDomainRating: hasTargetDr ? targetDr : null,
 			attribution: rated.added || hasTargetDr ? DR_ATTRIBUTION : null,
+			leftOut: note,
 			total: rated.rows.length,
 			offset,
 			rows: rated.rows.slice(offset, offset + 50)
@@ -37999,12 +38068,13 @@ async function runLostPages(input, deps) {
 			`${lost.length} pages kept ${LOST_SHARE * 100}% or less of at least ${MIN_LOST} clicks${lost.length > CHECKED ? `; the top ${CHECKED} by clicks lost are shown` : ""}.`,
 			rows.length ? table(rows, Object.keys(rows[0] ?? {}), originOf(input.site)) : "No pages lost their clicks.",
 			"Live checks are fetched now with no redirects followed. Index status is from URL Inspection; Google allows about 2,000 inspections a day per property.",
+			temporaryRedirectNote(rows),
 			`Next: ${deps.call("page")} for one URL; ${deps.call("report", {
 				site: input.site,
 				section: "content-decay"
 			})} for pages that lost part of their clicks.`,
 			FACTS_ONLY
-		].join("\n\n"),
+		].filter(Boolean).join("\n\n"),
 		data: {
 			range,
 			comparisonRange: before,
@@ -38168,7 +38238,7 @@ const SHARED_TOOLS = [
 			...detail
 		}),
 		run: async (surface, input) => runReport$1({
-			site: await surface.resolveSite(input.site),
+			site: input.section === "bing" ? await surface.resolveSite(input.site).catch(() => input.site) : await surface.resolveSite(input.site),
 			section: input.section,
 			startDate: input.start_date,
 			endDate: input.end_date,