Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
Reject unusable rank-tracker locations at save time and stop reporting empty runs as completed (#613)
Ben Senescue8a958a04f69
diff --git a/chatgpt-app-submission.json b/chatgpt-app-submission.jsonindex 5e25f1ed..8eae3080 100644--- a/chatgpt-app-submission.json+++ b/chatgpt-app-submission.json@@ -164,6 +164,18 @@"destructive_justification": "May use metered research credits but does not delete, overwrite, revoke access, send, or publish anything."}},+ "search_serp_locations": {+ "annotations": {+ "readOnlyHint": true,+ "openWorldHint": false,+ "destructiveHint": false+ },+ "justifications": {+ "read_only_justification": "Only reads Google's public location registry to resolve a place name; uses no credits.",+ "open_world_justification": "Operates only on private OpenSEO state or private provider data and cannot change publicly visible internet state.",+ "destructive_justification": "Does not delete, overwrite, revoke access, send messages, or perform irreversible actions."+ }+ },"create_rank_tracker": {"annotations": {"readOnlyHint": false,diff --git a/package.json b/package.jsonindex 86bd3909..2a1c4302 100644--- a/package.json+++ b/package.json@@ -50,6 +50,7 @@"billing:usage": "tsx scripts/dataforseo-account-usage.ts","cleanup:default-projects:d1": "tsx scripts/d1-default-project-cleanup.ts","gdpr:erase-user": "tsx scripts/erase-user-data.ts",+ "repair:rank-locations": "tsx scripts/repair-rank-tracking-locations.ts","seed:rank-tracking": "tsx scripts/seed-rank-tracking.ts","seed:projects": "tsx scripts/seed-projects.ts","ci:check": "prettier --check . && knip && tsc --noEmit && tsc --noEmit -p badseo/tsconfig.json && oxlint . --type-aware && pnpm sync-plugin-skills && test -z \"$(git status --porcelain -- plugins/openseo/skills)\""diff --git a/scripts/cli-utils.ts b/scripts/cli-utils.tsindex fef4eed4..ab38ab10 100644--- a/scripts/cli-utils.ts+++ b/scripts/cli-utils.ts@@ -39,3 +39,9 @@ export function loadLocalEnv() {}}}++export function requiredEnv(name: string): string {+ const value = process.env[name]?.trim();+ if (!value) throw new Error(`${name} is required.`);+ return value;+}diff --git a/scripts/rank-location-repair-support.ts b/scripts/rank-location-repair-support.tsnew file mode 100644index 00000000..374895a9--- /dev/null+++ b/scripts/rank-location-repair-support.ts@@ -0,0 +1,88 @@+/**+ * DataForSEO access for the rank-location repair: the free per-country+ * location registry (cached on disk) and the sandbox probe that tells us+ * whether a location_name will be accepted by the live SERP endpoints.+ */+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";+import { join } from "node:path";+import { z } from "zod";+import { probeSerpLocation } from "@/server/lib/dataforseo/serp-location-validate";+import { requiredEnv } from "./cli-utils";+import type { SerpRegistryLocation } from "./serp-location-match";++const registryItemSchema = z.object({+ location_code: z.number(),+ location_name: z.string(),+ location_type: z.string().nullable().optional(),+});++const registryResponseSchema = z.object({+ tasks: z.array(+ z.object({+ status_code: z.number(),+ status_message: z.string().optional(),+ result: z.array(z.unknown()).nullable().optional(),+ }),+ ),+});++export async function fetchRegistry(+ iso: string,+ cacheDir: string,+): Promise<SerpRegistryLocation[]> {+ mkdirSync(cacheDir, { recursive: true });+ const cachePath = join(cacheDir, `serp-locations-${iso}.json`);+ if (existsSync(cachePath)) {+ return JSON.parse(+ readFileSync(cachePath, "utf8"),+ ) as SerpRegistryLocation[];+ }+ const response = await fetch(+ `https://api.dataforseo.com/v3/serp/google/locations/${encodeURIComponent(iso)}`,+ {+ headers: { Authorization: `Basic ${requiredEnv("DATAFORSEO_API_KEY")}` },+ },+ );+ if (!response.ok) {+ throw new Error(`locations/${iso}: HTTP ${response.status}`);+ }+ const parsed = registryResponseSchema.parse(await response.json());+ const task = parsed.tasks[0];+ if (!task || task.status_code !== 20000) {+ throw new Error(+ `locations/${iso}: ${task?.status_code} ${task?.status_message ?? ""}`,+ );+ }+ const registry = (task.result ?? [])+ .map((item) => registryItemSchema.safeParse(item))+ .flatMap((item) => (item.success ? [item.data] : []))+ .map((item) => ({+ locationCode: item.location_code,+ locationName: item.location_name,+ locationType: item.location_type ?? "",+ }));+ writeFileSync(cachePath, JSON.stringify(registry));+ return registry;+}++/**+ * Ask the sandbox whether a location_name is accepted. The host is slow to+ * accept connections at times, so transport failures retry a few times+ * before giving up on the whole run.+ */+export async function sandboxAccepts(+ locationName: string,+ languageCode: string,+): Promise<{ ok: boolean; message: string }> {+ for (let attempt = 1; ; attempt++) {+ try {+ const task = await probeSerpLocation(locationName, languageCode, {+ signal: AbortSignal.timeout(30_000),+ });+ return { ok: task.status_code === 20000, message: task.status_message };+ } catch (error) {+ if (attempt >= 4) throw error;+ await new Promise((resolve) => setTimeout(resolve, 2000 * attempt));+ }+ }+}diff --git a/scripts/repair-rank-tracking-locations.ts b/scripts/repair-rank-tracking-locations.tsnew file mode 100644index 00000000..08d42842--- /dev/null+++ b/scripts/repair-rank-tracking-locations.ts@@ -0,0 +1,379 @@+/**+ * Rewrite free-form rank-tracker locations ("Catonsville, MD") to the canonical+ * DataForSEO `location_name` the SERP endpoints accept. Anything else is+ * rejected at check time with "Invalid Field: 'location_name'", so the tracker+ * "completes" every run with zero results (EVE-110 / EVE-138).+ *+ * Dry run (the default) prints every active tracker with a location name,+ * grouped by outcome, and writes a CSV next to the report:+ * pnpm repair:rank-locations+ *+ * Prove the rewrites are accepted before applying: --verify posts each+ * current and proposed name to the DataForSEO sandbox, which validates+ * request fields exactly like production at zero cost.+ * pnpm repair:rank-locations --verify+ *+ * Rows the matcher cannot settle (AMBIGUOUS / UNRESOLVED) take a human pick via+ * a JSON file of { "<trackerId>": "<exact registry locationName>" }, read from+ * .cache/rank-location-overrides.json when present (or --overrides <path>).+ * Overrides are sandbox-verified like every other rewrite and must exist in+ * the country's registry.+ *+ * Apply the RESOLVED rows after reviewing them, naming the host the dry run+ * printed so a stray .env can't point the write at the wrong database:+ * pnpm repair:rank-locations --apply <host>+ *+ * Needs POSTGRES_DATABASE_URL and DATAFORSEO_API_KEY (the locations endpoint+ * is free). Registries are cached under --cache-dir (default .cache/) so the+ * apply run does not refetch ~10MB per country.+ */+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";+import { join } from "node:path";+import process from "node:process";+import { and, eq, isNotNull, ne } from "drizzle-orm";+import { drizzle } from "drizzle-orm/postgres-js";+import postgres from "postgres";+import { z } from "zod";+import { rankTrackingConfigs } from "../src/db/pg/app.schema";+import {+ getIsoCountryCode,+ LOCATION_OPTIONS,+} from "../src/shared/keyword-locations";+import {+ foldSegment,+ matchSerpLocation,+ type SerpLocationMatch,+ type SerpRegistryLocation,+} from "./serp-location-match";+import { loadLocalEnv, parseArgs, requiredEnv } from "./cli-utils";+import { fetchRegistry, sandboxAccepts } from "./rank-location-repair-support";++loadLocalEnv();++const args = parseArgs(process.argv.slice(2));+const apply = args.apply !== undefined;+// Writes are always verified first: a name the sandbox already accepts is a+// working target and must not be replaced by the matcher's guess.+const verify = apply || args.verify === "true";+const cacheDir = args["cache-dir"] ?? ".cache";+const overridesPath =+ args.overrides ??+ (existsSync(join(cacheDir, "rank-location-overrides.json"))+ ? join(cacheDir, "rank-location-overrides.json")+ : null);+const overrides: Record<string, string> = overridesPath+ ? z+ .record(z.string().uuid(), z.string().min(1))+ .parse(JSON.parse(readFileSync(overridesPath, "utf8")))+ : {};+const reportPath = args.report ?? join(cacheDir, "rank-location-repair.csv");++/** Country location_codes we know; anything else can't pick a registry. */+const KNOWN_COUNTRY_CODES = new Set(+ LOCATION_OPTIONS.map((option) => option.code),+);++/**+ * A few trackers carry a city code (1027744 Seattle) or a bare ISO numeric+ * (36) in `location_code`, which the app treats as a country everywhere. Read+ * the country off the name's last segment so the row can be repaired fully.+ */+function countryFromName(+ locationName: string,+): (typeof LOCATION_OPTIONS)[number] | null {+ const last = foldSegment(locationName.split(",").at(-1) ?? "");+ return (+ LOCATION_OPTIONS.find((option) => foldSegment(option.label) === last) ??+ null+ );+}++type ConfigRow = {+ id: string;+ projectId: string;+ domain: string;+ locationCode: number;+ languageCode: string;+ locationName: string;+};++/** A human pick for one tracker; must name a real registry row. */+function applyOverride(+ configId: string,+ registry: SerpRegistryLocation[],+): SerpLocationMatch | null {+ const locationName = overrides[configId];+ if (!locationName) return null;+ const location = registry.find((row) => row.locationName === locationName);+ if (!location) {+ throw new Error(+ `--overrides: "${locationName}" is not in the registry for ${configId}`,+ );+ }+ return { kind: "resolved", location, via: "override" };+}++type Outcome = {+ config: ConfigRow;+ iso: string | null;+ match: SerpLocationMatch | null;+ /** Set when `location_code` is not a country code and the name says which. */+ countryCodeFix: number | null;+};++function describe(outcome: Outcome): string {+ const { match } = outcome;+ if (!match) return `unknown country code ${outcome.config.locationCode}`;+ const codeFix =+ outcome.countryCodeFix !== null+ ? ` + location_code ${outcome.config.locationCode} -> ${outcome.countryCodeFix}`+ : "";+ switch (match.kind) {+ case "exact":+ return `already canonical${codeFix}`;+ case "resolved":+ return `${match.location.locationName} (${match.location.locationType}, via ${match.via})${codeFix}`;+ case "ambiguous":+ return `ambiguous: ${match.candidates.map((c) => c.locationName).join(" | ")}`;+ case "unresolved":+ return match.suggestions.length > 0+ ? `no match; nearest: ${match.suggestions.map((c) => c.locationName).join(" | ")}`+ : "no match";+ }+}++function csvCell(value: string | number): string {+ const text = String(value);+ return /[",\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;+}++async function main() {+ const connectionString = requiredEnv("POSTGRES_DATABASE_URL");+ const host = new URL(connectionString).host;+ if (apply && args.apply !== host) {+ throw new Error(`--apply must name the database host: --apply ${host}`);+ }+ console.log(`${apply ? "APPLY" : "DRY RUN"} against ${host}`);+ if (overridesPath) console.log(`Using overrides from ${overridesPath}`);++ const client = postgres(connectionString, { max: 1 });+ const db = drizzle(client);+ try {+ const rows = await db+ .select({+ id: rankTrackingConfigs.id,+ projectId: rankTrackingConfigs.projectId,+ domain: rankTrackingConfigs.domain,+ locationCode: rankTrackingConfigs.locationCode,+ languageCode: rankTrackingConfigs.languageCode,+ locationName: rankTrackingConfigs.locationName,+ })+ .from(rankTrackingConfigs)+ .where(+ and(+ eq(rankTrackingConfigs.isActive, true),+ isNotNull(rankTrackingConfigs.locationName),+ ne(rankTrackingConfigs.locationName, ""),+ ),+ );+ const configs = rows.filter(+ (row): row is ConfigRow => row.locationName !== null,+ );+ console.log(`${configs.length} active trackers carry a location name`);++ const registries = new Map<string, SerpRegistryLocation[]>();+ const outcomes: Outcome[] = [];+ for (const config of configs) {+ let countryCodeFix: number | null = null;+ let iso: string;+ if (KNOWN_COUNTRY_CODES.has(config.locationCode)) {+ iso = getIsoCountryCode(config.locationCode);+ } else {+ const country = countryFromName(config.locationName);+ if (!country) {+ outcomes.push({+ config,+ iso: null,+ match: null,+ countryCodeFix: null,+ });+ continue;+ }+ countryCodeFix = country.code;+ iso = getIsoCountryCode(country.code);+ }+ let registry = registries.get(iso);+ if (!registry) {+ registry = await fetchRegistry(iso, cacheDir);+ registries.set(iso, registry);+ console.log(` registry ${iso}: ${registry.length} locations`);+ }+ outcomes.push({+ config,+ iso,+ match:+ applyOverride(config.id, registry) ??+ matchSerpLocation(config.locationName, registry, iso),+ countryCodeFix,+ });+ }+ for (const id of Object.keys(overrides)) {+ if (!configs.some((config) => config.id === id)) {+ throw new Error(+ `--overrides: ${id} is not an active tracker with a location name`,+ );+ }+ }++ const byKind = (kind: SerpLocationMatch["kind"] | null) =>+ outcomes.filter((o) => (o.match?.kind ?? null) === kind);+ const rewrites = outcomes.filter(+ (o) =>+ o.match?.kind === "resolved" ||+ (o.match?.kind === "exact" && o.countryCodeFix !== null),+ );+ const groups: Array<[string, Outcome[]]> = [+ ["RESOLVED (will be rewritten)", rewrites],+ ["AMBIGUOUS (needs a human)", byKind("ambiguous")],+ ["UNRESOLVED (needs a human)", byKind("unresolved")],+ ["UNKNOWN COUNTRY CODE", byKind(null)],+ ];+ for (const [title, group] of groups) {+ console.log(`\n== ${title}: ${group.length}`);+ for (const outcome of group) {+ console.log(+ ` ${outcome.config.id} ${outcome.config.domain} [${outcome.iso ?? "?"}] "${outcome.config.locationName}" -> ${describe(outcome)}`,+ );+ }+ }+ console.log(+ `\n== EXACT (untouched): ${outcomes.filter((o) => o.match?.kind === "exact" && o.countryCodeFix === null).length}`,+ );++ const header = [+ "config_id",+ "project_id",+ "domain",+ "iso",+ "current",+ "outcome",+ "proposed",+ ];+ const lines = outcomes.map((o) =>+ [+ o.config.id,+ o.config.projectId,+ o.config.domain,+ o.iso ?? "",+ o.config.locationName,+ o.match?.kind ?? "unknown_country",+ o.match?.kind === "resolved"+ ? o.match.location.locationName+ : describe(o),+ ]+ .map(csvCell)+ .join(","),+ );+ mkdirSync(cacheDir, { recursive: true });+ writeFileSync(reportPath, [header.join(","), ...lines].join("\n") + "\n");+ console.log(`\nReport: ${reportPath}`);++ const verdicts = new Map<string, { ok: boolean; message: string }>();+ const verdictKey = (name: string, language: string) =>+ `${name}\u0000${language}`;+ if (verify) {+ // One sandbox call per distinct (name, language) pair, current and+ // proposed, so the report shows both the rejection and the fix.+ const pairs = new Map<string, { name: string; language: string }>();+ for (const outcome of rewrites) {+ if (!outcome.match || !("location" in outcome.match)) continue;+ for (const name of [+ outcome.config.locationName,+ outcome.match.location.locationName,+ ]) {+ pairs.set(verdictKey(name, outcome.config.languageCode), {+ name,+ language: outcome.config.languageCode,+ });+ }+ }+ const entries = [...pairs.entries()];+ for (let i = 0; i < entries.length; i += 5) {+ await Promise.all(+ entries.slice(i, i + 5).map(async ([key, pair]) => {+ verdicts.set(key, await sandboxAccepts(pair.name, pair.language));+ }),+ );+ }+ let currentAccepted = 0;+ let proposedRejected = 0;+ console.log(`\n== SANDBOX VERIFY (${entries.length} distinct names)`);+ for (const outcome of rewrites) {+ if (!outcome.match || !("location" in outcome.match)) continue;+ const language = outcome.config.languageCode;+ const before = verdicts.get(+ verdictKey(outcome.config.locationName, language),+ );+ const after = verdicts.get(+ verdictKey(outcome.match.location.locationName, language),+ );+ if (before?.ok) {+ currentAccepted += 1;+ console.log(+ ` KEEP NAME ${outcome.config.id} "${outcome.config.locationName}" (${language}) is already accepted; only a location_code fix (if any) will be applied`,+ );+ }+ if (!after?.ok) {+ proposedRejected += 1;+ console.log(+ ` REJECTED ${outcome.config.id} "${outcome.match.location.locationName}" (${language}): ${after?.message ?? "no verdict"}`,+ );+ }+ }+ console.log(+ ` proposed names accepted: ${rewrites.length - proposedRejected}/${rewrites.length}; current names already accepted: ${currentAccepted}/${rewrites.length}`,+ );+ }++ if (!apply) {+ console.log(+ `Dry run only. Re-run with --apply ${host} to rewrite the RESOLVED rows.`,+ );+ return;+ }++ let written = 0;+ for (const outcome of rewrites) {+ if (!outcome.match || !("location" in outcome.match)) continue;+ const current = verdicts.get(+ verdictKey(outcome.config.locationName, outcome.config.languageCode),+ );+ const proposed = verdicts.get(+ verdictKey(+ outcome.match.location.locationName,+ outcome.config.languageCode,+ ),+ );+ const keepName = current?.ok === true;+ if (keepName && outcome.countryCodeFix === null) continue;+ if (!keepName && proposed?.ok !== true) continue;+ await db+ .update(rankTrackingConfigs)+ .set({+ ...(keepName+ ? {}+ : { locationName: outcome.match.location.locationName }),+ ...(outcome.countryCodeFix !== null+ ? { locationCode: outcome.countryCodeFix }+ : {}),+ })+ .where(eq(rankTrackingConfigs.id, outcome.config.id));+ written += 1;+ }+ console.log(`Rewrote ${written} tracker location(s).`);+ } finally {+ await client.end();+ }+}++await main();diff --git a/scripts/serp-location-match.test.ts b/scripts/serp-location-match.test.tsnew file mode 100644index 00000000..938f47ca--- /dev/null+++ b/scripts/serp-location-match.test.ts@@ -0,0 +1,101 @@+import { describe, expect, it } from "vitest";+import {+ matchSerpLocation,+ type SerpRegistryLocation,+} from "./serp-location-match";++const loc = (+ locationName: string,+ locationType = "City",+ locationCode = locationName.length,+): SerpRegistryLocation => ({ locationCode, locationName, locationType });++const US: SerpRegistryLocation[] = [+ loc("United States", "Country"),+ loc("Maryland,United States", "State"),+ loc("Catonsville,Maryland,United States"),+ loc("Portland,Oregon,United States"),+ loc("Portland, OR,United States", "DMA Region"),+ loc("Portland,Maine,United States"),+ loc("Seattle,Washington,United States"),+ loc(+ "Seattle–Tacoma International Airport,Washington,United States",+ "Airport",+ ),+ loc("21228,Maryland,United States", "Postal Code"),+];++const BR: SerpRegistryLocation[] = [+ loc("Curitiba,State of Parana,Brazil"),+ loc("Itajai,State of Santa Catarina,Brazil"),+ loc("Itajai,Itajai,State of Santa Catarina,Brazil"),+];++describe("matchSerpLocation", () => {+ it("returns the registry row untouched when the name is already canonical", () => {+ expect(+ matchSerpLocation("Catonsville,Maryland,United States", US, "us"),+ ).toEqual({+ kind: "exact",+ location: US[2],+ });+ });++ it("forgives spacing, case and accents", () => {+ expect(+ matchSerpLocation("seattle, washington, united states", US, "us"),+ ).toMatchObject({+ kind: "resolved",+ via: "normalized",+ location: { locationName: "Seattle,Washington,United States" },+ });+ expect(+ matchSerpLocation("Itajaí, Santa Catarina, Brazil", BR, "br"),+ ).toMatchObject({+ location: { locationName: "Itajai,State of Santa Catarina,Brazil" },+ });+ });++ it("expands a state abbreviation and fills in the missing country", () => {+ expect(matchSerpLocation("Catonsville, MD", US, "us")).toMatchObject({+ kind: "resolved",+ via: "expanded",+ location: { locationName: "Catonsville,Maryland,United States" },+ });+ });++ it("refuses a bare name shared by several places", () => {+ const match = matchSerpLocation("Portland", US, "us");+ expect(match.kind).toBe("ambiguous");+ if (match.kind !== "ambiguous") return;+ expect(match.candidates.slice(0, 2).map((c) => c.locationName)).toEqual([+ "Portland,Maine,United States",+ "Portland,Oregon,United States",+ ]);+ });++ it("prefers the city over a DMA and never picks postal codes or airports", () => {+ expect(matchSerpLocation("Portland metro, Oregon", US, "us")).toMatchObject(+ {+ location: { locationName: "Portland,Oregon,United States" },+ },+ );+ expect(matchSerpLocation("Seattle", US, "us")).toMatchObject({+ location: { locationName: "Seattle,Washington,United States" },+ });+ expect(matchSerpLocation("21228", US, "us").kind).toBe("unresolved");+ });++ it("prefers the whole place over a same-named level nested inside it", () => {+ expect(matchSerpLocation("Itajai", BR, "br")).toMatchObject({+ location: { locationName: "Itajai,State of Santa Catarina,Brazil" },+ });+ });++ it("offers nearby suggestions when nothing matches", () => {+ expect(matchSerpLocation("Catonsville, Delaware", US, "us")).toMatchObject({+ kind: "unresolved",+ suggestions: [{ locationName: "Catonsville,Maryland,United States" }],+ });+ });+});diff --git a/scripts/serp-location-match.ts b/scripts/serp-location-match.tsnew file mode 100644index 00000000..ddf154d2--- /dev/null+++ b/scripts/serp-location-match.ts@@ -0,0 +1,192 @@+/**+ * Resolve a free-form location string ("Catonsville, MD", "Mexico City",+ * "Seattle, Washington, United States") to the one canonical DataForSEO+ * `location_name` the SERP endpoints accept ("Catonsville,Maryland,United+ * States"). DataForSEO matches `location_name` verbatim, so anything else —+ * spacing, abbreviations, accents, a missing country — is rejected at call+ * time with "Invalid Field: 'location_name'".+ *+ * Pure and Node-safe: callers hand in one country's registry (see+ * fetchSerpLocationsForCountry / the repair script).+ */++import {+ foldLocationText as foldSegment,+ LOCATION_TYPE_RANK,+ REGION_ABBREVIATIONS,+} from "../src/shared/serp-location-search";++export { foldSegment };++export interface SerpRegistryLocation {+ locationCode: number;+ locationName: string;+ locationType: string;+}++export type SerpLocationMatch =+ | { kind: "exact"; location: SerpRegistryLocation }+ | {+ kind: "resolved";+ location: SerpRegistryLocation;+ /** Which rewrite produced the match, for review output. */+ via: "normalized" | "expanded" | "override";+ }+ | { kind: "ambiguous"; candidates: SerpRegistryLocation[] }+ | { kind: "unresolved"; suggestions: SerpRegistryLocation[] };++/** Endonyms and shorthands seen in production that the registry spells in English. */+const NAME_ALIASES: Record<string, string> = {+ usa: "United States",+ us: "United States",+ uk: "United Kingdom",+ "great britain": "United Kingdom",+ england: "United Kingdom",+ norge: "Norway",+ espana: "Spain",+ wien: "Vienna",+ "ciudad de mexico": "Mexico City",+ cdmx: "Mexico City",+ deutschland: "Germany",+ schweiz: "Switzerland",+ italia: "Italy",+ brasil: "Brazil",+ sverige: "Sweden",+ danmark: "Denmark",+ nederland: "Netherlands",+ bangalore: "Bengaluru",+};++function splitSegments(name: string): string[] {+ return name+ .split(",")+ .map((segment) => segment.trim())+ .filter((segment) => segment.length > 0);+}++function foldedKey(name: string): string {+ return splitSegments(name).map(foldSegment).join(",");+}++/** "Portland metro" / "Denver area" mean the place itself. */+const NOISE_SUFFIX_RE = /\s+(metro(?:\s+area)?|area|region)$/i;++function expandSegments(segments: string[], countryCode: string): string[] {+ const abbreviations = REGION_ABBREVIATIONS[countryCode] ?? {};+ return segments.map((segment, index) => {+ if (index === 0) segment = segment.replace(NOISE_SUFFIX_RE, "");+ const folded = foldSegment(segment);+ const alias = NAME_ALIASES[folded];+ if (alias) return alias;+ // Abbreviations only make sense after a place name, never as the place.+ if (index > 0) {+ const region = abbreviations[folded];+ if (region) return region;+ }+ return segment;+ });+}++/** Brazil's registry spells regions "State of Parana"; users write "Parana". */+function segmentsEqual(user: string, registry: string): boolean {+ return user === registry || registry === `state of ${user}`;+}++/**+ * True when `needle` appears in `haystack` in order (gaps allowed). A user+ * segment that repeats the place name ("Hanoi,Hanoi,Vietnam") is skipped+ * when the registry has no such level.+ */+function isOrderedSubsequence(needle: string[], haystack: string[]): boolean {+ let position = 0;+ for (const [index, item] of needle.entries()) {+ const found = haystack.findIndex(+ (candidate, at) => at >= position && segmentsEqual(item, candidate),+ );+ if (found < 0) {+ if (index > 0 && item === needle[0]) continue;+ return false;+ }+ position = found + 1;+ }+ return true;+}++function typeRank(location: SerpRegistryLocation): number {+ return LOCATION_TYPE_RANK[location.locationType] ?? Number.POSITIVE_INFINITY;+}++/**+ * Rank candidates that share the user's first segment as their place name and+ * contain every user segment in order. Fewer registry segments win (the city+ * itself over a same-named suburb inside it), then the more common place type.+ */+function rankCandidates(+ userSegments: string[],+ registry: SerpRegistryLocation[],+): SerpRegistryLocation[] {+ const folded = userSegments.map(foldSegment);+ const [place] = folded;+ if (!place) return [];+ const candidates = registry+ .filter((location) => Number.isFinite(typeRank(location)))+ .map((location) => ({+ location,+ segments: splitSegments(location.locationName).map(foldSegment),+ }))+ .filter(+ ({ segments }) =>+ segments[0] === place && isOrderedSubsequence(folded, segments),+ );+ candidates.sort(+ (a, b) =>+ a.segments.length - b.segments.length ||+ typeRank(a.location) - typeRank(b.location) ||+ a.location.locationName.localeCompare(b.location.locationName),+ );+ return candidates.map(({ location }) => location);+}++/** Candidates that tie on segment count and type are different places. */+function isUniqueBest(ranked: SerpRegistryLocation[]): boolean {+ if (ranked.length < 2) return true;+ const [best, next] = ranked;+ return (+ splitSegments(best.locationName).length !==+ splitSegments(next.locationName).length ||+ typeRank(best) !== typeRank(next)+ );+}++export function matchSerpLocation(+ input: string,+ registry: SerpRegistryLocation[],+ countryCode: string,+): SerpLocationMatch {+ const trimmed = input.trim();+ const exact = registry.find((location) => location.locationName === trimmed);+ if (exact) return { kind: "exact", location: exact };++ const key = foldedKey(trimmed);+ const normalized = registry.find(+ (location) => foldedKey(location.locationName) === key,+ );+ if (normalized) {+ return { kind: "resolved", location: normalized, via: "normalized" };+ }++ const segments = expandSegments(splitSegments(trimmed), countryCode);+ const ranked = rankCandidates(segments, registry);+ if (ranked.length === 0) {+ // Suggest places that merely start with the user's first word so a human+ // (or an agent) can pick.+ const suggestions = segments[0]+ ? rankCandidates([segments[0]], registry).slice(0, 3)+ : [];+ return { kind: "unresolved", suggestions };+ }+ if (!isUniqueBest(ranked)) {+ return { kind: "ambiguous", candidates: ranked.slice(0, 5) };+ }+ return { kind: "resolved", location: ranked[0], via: "expanded" };+}diff --git a/src/client/features/ai-mcp/AvailableTools.tsx b/src/client/features/ai-mcp/AvailableTools.tsxindex dc0e95eb..b6b2aee4 100644--- a/src/client/features/ai-mcp/AvailableTools.tsx+++ b/src/client/features/ai-mcp/AvailableTools.tsx@@ -40,6 +40,12 @@ const toolCategories: ToolCategory[] = [title: "Get rank tracking positions",description: "Read tracked keyword positions.",},+ {+ name: "search_serp_locations",+ title: "Find a local search location",+ description:+ "Look up the exact Google location name to track a city in.",+ },{name: "create_rank_tracker",title: "Create a rank tracker",diff --git a/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx b/src/client/features/rank-tracking/RankTrackingDomainDetail.tsxindex b30de34a..4e8b1eea 100644--- a/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx+++ b/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx@@ -215,6 +215,16 @@ export function RankTrackingDomainDetail({</div>)}+ {latestRun?.status === "failed" && !isRunning && (+ <div className="alert alert-error text-sm py-2">+ <AlertTriangle className="size-4" />+ <span>+ <span className="font-medium">Last check failed.</span>{" "}+ {latestRun.errorMessage}+ </span>+ </div>+ )}+<FreePlanAlert visible={isFreePlan} />{/* Results card */}diff --git a/src/server/features/rank-tracking/repositories/RankTrackingRepository.ts b/src/server/features/rank-tracking/repositories/RankTrackingRepository.tsindex 84f668b0..35682773 100644--- a/src/server/features/rank-tracking/repositories/RankTrackingRepository.ts+++ b/src/server/features/rank-tracking/repositories/RankTrackingRepository.ts@@ -2,7 +2,6 @@ import {and,asc,count,- desc,eq,inArray,isNull,@@ -15,7 +14,6 @@ import { db } from "@/db";import {rankTrackingConfigs,rankCheckRuns,- rankSnapshots,rankTrackingKeywords,projects,} from "@/db/schema";@@ -29,6 +27,16 @@ import {getConfigTrend,getPositionMatrix,} from "./snapshotQueries";+import {+ tryCreateRun,+ updateRun,+ setRunErrorIfEmpty,+ getRunById,+ getLatestRunForConfig,+ getActiveRunForConfig,+ insertSnapshots,+ getSnapshotsForRun,+} from "./runQueries";// ---------------------------------------------------------------------------// Config CRUD@@ -198,110 +206,6 @@ async function claimDueConfig(input: {return claimed.length > 0;}-// ----------------------------------------------------------------------------// Run CRUD-// -----------------------------------------------------------------------------/**- * Try to insert a new pending run. Returns true when inserted, or false if blocked- * by the partial unique index on (config_id) WHERE status IN ('pending',- * 'running') — i.e. another active run exists for this config.- *- * This is how duplicate-trigger protection is enforced: the DB rejects the- * second insert rather than a separate lock table.- */-async function tryCreateRun(data: {- id: string;- configId: string;- projectId: string;- keywordsTotal: number;- isSubsetRun?: boolean;-}) {- const inserted = await db- .insert(rankCheckRuns)- .values({ ...data, status: "pending" })- .onConflictDoNothing()- .returning({ id: rankCheckRuns.id });- return Boolean(inserted[0]);-}--async function updateRun(- runId: string,- data: Partial<InferInsertModel<typeof rankCheckRuns>>,-) {- await db.update(rankCheckRuns).set(data).where(eq(rankCheckRuns.id, runId));-}--async function getRunById(runId: string) {- const rows = await db- .select()- .from(rankCheckRuns)- .where(eq(rankCheckRuns.id, runId))- .limit(1);- return rows[0] ?? null;-}--async function getLatestRunForConfig(configId: string) {- const rows = await db- .select()- .from(rankCheckRuns)- .where(eq(rankCheckRuns.configId, configId))- .orderBy(desc(rankCheckRuns.startedAt))- .limit(1);- return rows[0] ?? null;-}--/**- * Returns the currently active (pending or running) run for a config, if any.- * At most one such row exists, enforced by the partial unique index.- */-async function getActiveRunForConfig(configId: string) {- const rows = await db- .select()- .from(rankCheckRuns)- .where(- and(- eq(rankCheckRuns.configId, configId),- inArray(rankCheckRuns.status, ["pending", "running"]),- ),- )- .limit(1);- return rows[0] ?? null;-}--// ----------------------------------------------------------------------------// Snapshots-// -----------------------------------------------------------------------------async function insertSnapshots(- snapshots: Array<- Omit<InferInsertModel<typeof rankSnapshots>, "id" | "checkedAt">- >,-) {- // Target the (run, keyword, device) unique index explicitly. An UNtargeted- // ON CONFLICT DO NOTHING also swallows a primary-key collision, which would- // silently drop every row if the `id` serial sequence ever drifts behind- // max(id) (e.g. after a data import that copied explicit ids). Scoping the- // clause to the intended dedupe index keeps re-runs idempotent while letting- // a pk collision surface as a loud duplicate-key error instead of data loss.- await executeInBatches(snapshots, (tx, snapshot) =>- tx- .insert(rankSnapshots)- .values(snapshot)- .onConflictDoNothing({- target: [- rankSnapshots.runId,- rankSnapshots.trackingKeywordId,- rankSnapshots.device,- ],- }),- );-}--async function getSnapshotsForRun(runId: string) {- return db.select().from(rankSnapshots).where(eq(rankSnapshots.runId, runId));-}-// ---------------------------------------------------------------------------// Tracking keywords per config// ---------------------------------------------------------------------------@@ -474,6 +378,7 @@ export const RankTrackingRepository = {claimDueConfig,tryCreateRun,updateRun,+ setRunErrorIfEmpty,getRunById,getLatestRunForConfig,getActiveRunForConfig,diff --git a/src/server/features/rank-tracking/repositories/runQueries.ts b/src/server/features/rank-tracking/repositories/runQueries.tsnew file mode 100644index 00000000..1e10128e--- /dev/null+++ b/src/server/features/rank-tracking/repositories/runQueries.ts@@ -0,0 +1,123 @@+import { and, desc, eq, inArray, isNull } from "drizzle-orm";+import type { InferInsertModel } from "drizzle-orm";+import { db } from "@/db";+import { rankCheckRuns, rankSnapshots } from "@/db/schema";+import { executeInBatches } from "@/db/runBatch";++// ---------------------------------------------------------------------------+// Run CRUD+// ---------------------------------------------------------------------------++/**+ * Try to insert a new pending run. Returns true when inserted, or false if blocked+ * by the partial unique index on (config_id) WHERE status IN ('pending',+ * 'running') — i.e. another active run exists for this config.+ *+ * This is how duplicate-trigger protection is enforced: the DB rejects the+ * second insert rather than a separate lock table.+ */+export async function tryCreateRun(data: {+ id: string;+ configId: string;+ projectId: string;+ keywordsTotal: number;+ isSubsetRun?: boolean;+}) {+ const inserted = await db+ .insert(rankCheckRuns)+ .values({ ...data, status: "pending" })+ .onConflictDoNothing()+ .returning({ id: rankCheckRuns.id });+ return Boolean(inserted[0]);+}++export async function updateRun(+ runId: string,+ data: Partial<InferInsertModel<typeof rankCheckRuns>>,+) {+ await db.update(rankCheckRuns).set(data).where(eq(rankCheckRuns.id, runId));+}++/**+ * Record why a keyword failed, first reason wins. Batch steps call this on+ * each rejection so finalize can show the vendor's actual message instead of+ * a generic "could not be checked".+ */+export async function setRunErrorIfEmpty(runId: string, errorMessage: string) {+ await db+ .update(rankCheckRuns)+ .set({ errorMessage })+ .where(+ and(eq(rankCheckRuns.id, runId), isNull(rankCheckRuns.errorMessage)),+ );+}++export async function getRunById(runId: string) {+ const rows = await db+ .select()+ .from(rankCheckRuns)+ .where(eq(rankCheckRuns.id, runId))+ .limit(1);+ return rows[0] ?? null;+}++export async function getLatestRunForConfig(configId: string) {+ const rows = await db+ .select()+ .from(rankCheckRuns)+ .where(eq(rankCheckRuns.configId, configId))+ .orderBy(desc(rankCheckRuns.startedAt))+ .limit(1);+ return rows[0] ?? null;+}++/**+ * Returns the currently active (pending or running) run for a config, if any.+ * At most one such row exists, enforced by the partial unique index.+ */+export async function getActiveRunForConfig(configId: string) {+ const rows = await db+ .select()+ .from(rankCheckRuns)+ .where(+ and(+ eq(rankCheckRuns.configId, configId),+ inArray(rankCheckRuns.status, ["pending", "running"]),+ ),+ )+ .limit(1);+ return rows[0] ?? null;+}++// ---------------------------------------------------------------------------+// Snapshots+// ---------------------------------------------------------------------------++export async function insertSnapshots(+ snapshots: Array<+ Omit<InferInsertModel<typeof rankSnapshots>, "id" | "checkedAt">+ >,+) {+ // Target the (run, keyword, device) unique index explicitly. An UNtargeted+ // ON CONFLICT DO NOTHING also swallows a primary-key collision, which would+ // silently drop every row if the `id` serial sequence ever drifts behind+ // max(id) (e.g. after a data import that copied explicit ids). Scoping the+ // clause to the intended dedupe index keeps re-runs idempotent while letting+ // a pk collision surface as a loud duplicate-key error instead of data loss.+ await executeInBatches(snapshots, (tx, snapshot) =>+ tx+ .insert(rankSnapshots)+ .values(snapshot)+ .onConflictDoNothing({+ target: [+ rankSnapshots.runId,+ rankSnapshots.trackingKeywordId,+ rankSnapshots.device,+ ],+ }),+ );+}++export async function getSnapshotsForRun(runId: string) {+ return db.select().from(rankSnapshots).where(eq(rankSnapshots.runId, runId));+}diff --git a/src/server/features/rank-tracking/services/RankTrackingService.test.ts b/src/server/features/rank-tracking/services/RankTrackingService.test.tsindex d26a8c6d..b998123e 100644--- a/src/server/features/rank-tracking/services/RankTrackingService.test.ts+++ b/src/server/features/rank-tracking/services/RankTrackingService.test.ts@@ -11,6 +11,10 @@ const mocks = vi.hoisted(() => ({}));vi.mock("cloudflare:workers", () => ({ env: {} }));+vi.mock("@/server/lib/runtime-env", () => ({+ getRequiredEnvValue: () => Promise.resolve("basic-key"),+ isHostedServerAuthMode: () => Promise.resolve(false),+}));vi.mock("@/server/lib/dataforseo", () => ({ createDataforseoClient: vi.fn() }));vi.mock("@/server/features/rank-tracking/repositories/RankTrackingRepository",@@ -41,8 +45,25 @@ const baseInput = {scheduleInterval: "daily" as const,};+/** The DataForSEO sandbox reply the location validator parses. */+function stubSandbox(statusCode: number, statusMessage = "Ok.") {+ vi.stubGlobal(+ "fetch",+ vi.fn().mockResolvedValue(+ new Response(+ JSON.stringify({+ tasks: [{ status_code: statusCode, status_message: statusMessage }],+ }),+ { status: 200 },+ ),+ ),+ );+}+describe("RankTrackingService.createConfig", () => {- beforeEach(() => {});+ beforeEach(() => {+ stubSandbox(20000);+ });it("reactivates an archived config instead of throwing, applying the new settings", async () => {mocks.getConfigByProjectDomainLocation.mockResolvedValue(archivedConfig);@@ -198,4 +219,19 @@ describe("RankTrackingService.createConfig", () => {expect.objectContaining({ locationCode: 2276, languageCode: "de" }),);});++ it("rejects a locationName the sandbox refuses, pointing at search_serp_locations", async () => {+ stubSandbox(40501, "Invalid Field: 'location_name'.");+ mocks.getConfigByProjectDomainLocation.mockResolvedValue(null);+ mocks.getConfigsForProject.mockResolvedValue([]);++ const error = await RankTrackingService.createConfig({+ ...baseInput,+ locationName: "Catonsville, MD",+ }).catch((thrown: unknown) => thrown);++ expect(error).toMatchObject({ code: "VALIDATION_ERROR" });+ expect(String(error)).toContain("search_serp_locations");+ expect(mocks.createConfig).not.toHaveBeenCalled();+ });});diff --git a/src/server/features/rank-tracking/services/RankTrackingService.ts b/src/server/features/rank-tracking/services/RankTrackingService.tsindex 81117e05..87ece4e6 100644--- a/src/server/features/rank-tracking/services/RankTrackingService.ts+++ b/src/server/features/rank-tracking/services/RankTrackingService.ts@@ -8,6 +8,7 @@ import {fetchKeywordMetricsForList,} from "@/server/lib/dataforseo";import { RankTrackingRepository } from "@/server/features/rank-tracking/repositories/RankTrackingRepository";+import { assertSerpLocationNameAccepted } from "@/server/lib/dataforseo/serp-location-validate";import { AppError } from "@/server/lib/errors";import { isHostedServerAuthMode } from "@/server/lib/runtime-env";import type {@@ -26,6 +27,7 @@ import {rankCheckCostApprovalError,} from "@/shared/rank-tracking";import {+ getIsoCountryCode,resolveKeywordDataLanguage,resolveMarket,} from "@/shared/keyword-locations";@@ -60,6 +62,16 @@ async function createConfig(input: {: null;const locationName = input.locationName ?? null;+ // Before the duplicate/limit checks so an unusable location name is the+ // error the caller sees.+ if (locationName) {+ await assertSerpLocationNameAccepted({+ locationName,+ languageCode,+ countryCode: getIsoCountryCode(locationCode),+ });+ }+const existing =await RankTrackingRepository.getConfigByProjectDomainLocation(input.projectId,@@ -148,6 +160,29 @@ async function updateConfig() {const updates: typeof input & { nextCheckAt?: string | null } = {};+ // A location name is only valid together with its market, so re-check the+ // resulting (name, language, country) whenever any of the three changes.+ const marketChanged =+ input.locationName !== undefined ||+ input.locationCode !== undefined ||+ input.languageCode !== undefined;+ if (marketChanged) {+ const existing = await getValidatedConfig(configId, projectId);+ const locationName =+ input.locationName === undefined+ ? existing.locationName+ : input.locationName;+ if (locationName) {+ await assertSerpLocationNameAccepted({+ locationName,+ languageCode: input.languageCode ?? existing.languageCode,+ countryCode: getIsoCountryCode(+ input.locationCode ?? existing.locationCode,+ ),+ });+ }+ }+if (input.domain !== undefined)updates.domain = normalizeDomain(input.domain);if (input.locationCode !== undefined)diff --git a/src/server/features/rank-tracking/services/rankTrackingResults.ts b/src/server/features/rank-tracking/services/rankTrackingResults.tsindex aa93e8c3..7824479e 100644--- a/src/server/features/rank-tracking/services/rankTrackingResults.ts+++ b/src/server/features/rank-tracking/services/rankTrackingResults.ts@@ -27,6 +27,7 @@ export async function getLatestResults(run: {id: string;lastCheckedAt: string | null;+ completedAt: string | null;status: "pending" | "running" | "completed" | "failed";errorMessage: string | null;} | null;@@ -138,7 +139,10 @@ export async function getLatestResults(run: latestRun? {id: latestRun.id,+ // Snapshot-derived: a run that saved zero snapshots leaves this+ // null even though it finished, so read completedAt for the run.lastCheckedAt: latestStartedAt,+ completedAt: latestRun.completedAt,status: latestRun.status,errorMessage: latestRun.errorMessage,}diff --git a/src/server/features/sam/samChatTools.ts b/src/server/features/sam/samChatTools.tsindex 6d2ad4a6..01bd8178 100644--- a/src/server/features/sam/samChatTools.ts+++ b/src/server/features/sam/samChatTools.ts@@ -14,6 +14,7 @@ import { estimateRankTrackerCostTool } from "@/server/mcp/tools/estimate-rank-trimport { getRankTrackerTool } from "@/server/mcp/tools/get-rank-tracker";import { removeRankTrackingKeywordsTool } from "@/server/mcp/tools/remove-rank-tracking-keywords";import { runRankTrackerTool } from "@/server/mcp/tools/run-rank-tracker";+import { searchSerpLocationsTool } from "@/server/mcp/tools/search-serp-locations";import { getSerpResultsTool } from "@/server/mcp/tools/get-serp-results";import {getAuditIssuesTool,@@ -369,6 +370,7 @@ export function buildSamMcpTools(get_backlinks_overview: adaptTool(getBacklinksOverviewTool),get_backlinks_profile: adaptTool(getBacklinksProfileTool),get_serp_results: adaptTool(getSerpResultsTool),+ search_serp_locations: adaptTool(searchSerpLocationsTool),create_rank_tracker: adaptTool(createRankTrackerTool),get_rank_tracker: adaptTool(getRankTrackerTool),add_rank_tracking_keywords: adaptTool(addRankTrackingKeywordsTool),diff --git a/src/server/lib/dataforseo/core.ts b/src/server/lib/dataforseo/core.tsindex d8fd74a4..a28cd791 100644--- a/src/server/lib/dataforseo/core.ts+++ b/src/server/lib/dataforseo/core.ts@@ -160,6 +160,9 @@ type DataforseoRequestOptions = {* be replayed. Defaults to retrying idempotent reads on transient 5xx.*/maxServerErrorRetries?: number;+ /** The sandbox host validates requests like production at zero cost. */+ baseUrl?: string;+ signal?: AbortSignal;};async function requestDataforseo<TTask extends DataforseoTaskLike>(@@ -172,13 +175,14 @@ async function requestDataforseo<TTask extends DataforseoTaskLike>(options.classify,options.maxServerErrorRetries,);- const response = await doFetch(`${API_BASE}${path}`, {+ const response = await doFetch(`${options.baseUrl ?? API_BASE}${path}`, {method,headers: {Accept: "application/json",...(method === "POST" ? { "Content-Type": "application/json" } : {}),},body: method === "POST" ? JSON.stringify(body) : undefined,+ signal: options.signal,});const text = await response.text();if (text === "") return null;diff --git a/src/server/lib/dataforseo/envelope.ts b/src/server/lib/dataforseo/envelope.tsindex 6e747719..e8845e91 100644--- a/src/server/lib/dataforseo/envelope.ts+++ b/src/server/lib/dataforseo/envelope.ts@@ -114,6 +114,11 @@ export function buildTaskBilling(const INVALID_FIELD_MESSAGE_RE = /Invalid Field:\s*'([^']+)'/i;+/** The request field a DataForSEO validation rejection names, if any. */+export function invalidFieldName(message: string): string | null {+ return message.match(INVALID_FIELD_MESSAGE_RE)?.[1] ?? null;+}+/*** DataForSEO echoes the posted request params back on `task.data`. Its* validation rejections are opaque ("Invalid Field: 'target'.") and name the@@ -125,10 +130,8 @@ function describeInvalidField(message: string,task: DataforseoTaskLike,): string {- const match = message.match(INVALID_FIELD_MESSAGE_RE);- if (!match) return message;- const field = match[1];- if (!isRecord(task.data)) return message;+ const field = invalidFieldName(message);+ if (!field || !isRecord(task.data)) return message;const value = task.data[field];if (value === undefined) return message;return `${message} (sent ${field}=${JSON.stringify(value)})`;diff --git a/src/server/lib/dataforseo/serp-location-validate.ts b/src/server/lib/dataforseo/serp-location-validate.tsnew file mode 100644index 00000000..34996aef--- /dev/null+++ b/src/server/lib/dataforseo/serp-location-validate.ts@@ -0,0 +1,85 @@+import { z } from "zod";+import { dataforseoPost } from "@/server/lib/dataforseo/core";+import { invalidFieldName } from "@/server/lib/dataforseo/envelope";+import { AppError } from "@/server/lib/errors";++const DATAFORSEO_SANDBOX_URL = "https://sandbox.dataforseo.com";+const SANDBOX_TIMEOUT_MS = 10_000;++const sandboxTaskSchema = z.object({+ status_code: z.number(),+ status_message: z.string(),+});++/**+ * Ask the DataForSEO sandbox whether a SERP task with this location and+ * language would be accepted. The sandbox returns canned results but validates+ * request fields exactly like production and costs nothing, so a 20000 here+ * means the live endpoint will take the name too.+ */+export function probeSerpLocation(+ locationName: string,+ languageCode: string,+ options: { signal?: AbortSignal } = {},+) {+ return dataforseoPost(+ "/v3/serp/google/organic/live/advanced",+ [+ {+ keyword: "pizza",+ location_name: locationName,+ language_code: languageCode,+ depth: 10,+ },+ ],+ { baseUrl: DATAFORSEO_SANDBOX_URL, signal: options.signal },+ ).then((response) => sandboxTaskSchema.parse(response?.tasks?.[0]));+}++/**+ * Reject a non-canonical `location_name` at save time instead of at check+ * time. DataForSEO matches `location_name` verbatim, so "Catonsville, MD"+ * fails every run with task status 40501 and the tracker silently records no+ * snapshots.+ *+ * Fails open: a sandbox outage must not block saving a tracker, and the worst+ * case is the pre-existing behaviour for that one config.+ */+export async function assertSerpLocationNameAccepted(input: {+ locationName: string;+ languageCode: string;+ countryCode?: string;+}): Promise<void> {+ let task: z.infer<typeof sandboxTaskSchema>;+ try {+ task = await probeSerpLocation(input.locationName, input.languageCode, {+ signal: AbortSignal.timeout(SANDBOX_TIMEOUT_MS),+ });+ } catch (error) {+ console.warn("[serp-location-validate] sandbox unavailable, skipping", {+ error: error instanceof Error ? error.message : String(error),+ });+ return;+ }++ if (task.status_code === 20000) return;+ // Only 4xxxx is "your request is wrong"; anything else is the provider's+ // problem and must not block the save.+ if (task.status_code < 40000 || task.status_code >= 50000) {+ console.warn(+ "[serp-location-validate] sandbox unavailable, skipping",+ task,+ );+ return;+ }+ if (invalidFieldName(task.status_message) !== "location_name") {+ throw new AppError(+ "VALIDATION_ERROR",+ `DataForSEO rejected this tracker: ${task.status_message}`,+ );+ }+ throw new AppError(+ "VALIDATION_ERROR",+ `"${input.locationName}" is not a Google location name. Call search_serp_locations({ query: "${input.locationName.split(",")[0].trim()}"${input.countryCode ? `, countryCode: "${input.countryCode}"` : ""} }) and pass the returned locationName exactly.`,+ );+}diff --git a/src/server/mcp/server.ts b/src/server/mcp/server.tsindex 806d1d50..fa6b4442 100644--- a/src/server/mcp/server.ts+++ b/src/server/mcp/server.ts@@ -21,6 +21,7 @@ import { estimateRankTrackerCostTool } from "@/server/mcp/tools/estimate-rank-trimport { getRankTrackerTool } from "@/server/mcp/tools/get-rank-tracker";import { removeRankTrackingKeywordsTool } from "@/server/mcp/tools/remove-rank-tracking-keywords";import { runRankTrackerTool } from "@/server/mcp/tools/run-rank-tracker";+import { searchSerpLocationsTool } from "@/server/mcp/tools/search-serp-locations";import { getSerpResultsTool } from "@/server/mcp/tools/get-serp-results";import {getGoogleAnalyticsAudienceBreakdownTool,@@ -170,6 +171,7 @@ export function createOpenSeoMcpServer(authProps: McpProps) {register(getBacklinksOverviewTool);register(getBacklinksProfileTool);register(getSerpResultsTool);+ register(searchSerpLocationsTool);register(createRankTrackerTool);register(getRankTrackerTool);register(addRankTrackingKeywordsTool);diff --git a/src/server/mcp/tools/create-rank-tracker.ts b/src/server/mcp/tools/create-rank-tracker.tsindex cc217669..c06ef2f7 100644--- a/src/server/mcp/tools/create-rank-tracker.ts+++ b/src/server/mcp/tools/create-rank-tracker.ts@@ -32,7 +32,9 @@ const inputSchema = {.min(1).max(200).optional()- .describe("Optional city or region name for local rank tracking."),+ .describe(+ 'Exact DataForSEO location name for local rank tracking, e.g. "Catonsville,Maryland,United States". Must come from search_serp_locations; free-form names like "Catonsville, MD" are rejected.',+ ),devices: z.enum(["desktop", "mobile", "both"]).optional()@@ -60,7 +62,7 @@ export const createRankTrackerTool = {config: {title: "Create rank tracker",description:- "Create a rank tracking configuration for a project. Creating an empty tracker uses no credits and starts no check, but daily, weekly, and monthly trackers will spend credits after keywords are added. The domain defaults to the project's domain; market defaults to the project's market; devices default to mobile, search depth to 40, and schedule to manual. Use estimate_rank_tracker_cost before adding keywords to a scheduled tracker or starting a live run. Call get_rank_tracker first to avoid duplicates.",+ "Create a rank tracking configuration for a project. Creating an empty tracker uses no credits and starts no check, but daily, weekly, and monthly trackers will spend credits after keywords are added. The domain defaults to the project's domain; market defaults to the project's market; devices default to mobile, search depth to 40, and schedule to manual. Use estimate_rank_tracker_cost before adding keywords to a scheduled tracker or starting a live run. Call get_rank_tracker first to avoid duplicates. For local (city-level) tracking, call search_serp_locations first and pass its locationName verbatim.",inputSchema,outputSchema: z.object({@@ -111,7 +113,7 @@ export const createRankTrackerTool = {);return mcpResponse({- text: `Created rank tracker ${config.id} for ${config.domain} (${config.devices}, top ${config.serpDepth}, ${config.scheduleInterval}). No keywords were added, no check was started, and no credits were used.${config.scheduleInterval === "manual" ? "" : " Scheduled checks will spend credits after keywords are added; estimate and obtain approval before adding them."}`,+ text: `Created rank tracker ${config.id} for ${config.domain} (${config.devices}, top ${config.serpDepth}, ${config.scheduleInterval}). No keywords were added, no check was started, and no credits were used.${config.locationName ? ` Local tracking for ${config.locationName}.` : ""}${config.scheduleInterval === "manual" ? "" : " Scheduled checks will spend credits after keywords are added; estimate and obtain approval before adding them."}`,meta: buildProjectMeta(context,args.projectId,diff --git a/src/server/mcp/tools/get-rank-tracker.ts b/src/server/mcp/tools/get-rank-tracker.tsindex d77bd685..bded4424 100644--- a/src/server/mcp/tools/get-rank-tracker.ts+++ b/src/server/mcp/tools/get-rank-tracker.ts@@ -28,6 +28,27 @@ const RANK_RESULT_COLUMNS: McpTableColumn<unknown>[] = [},];+/**+ * `lastCheckedAt` comes from the newest snapshot, so a run that finished+ * without saving any (e.g. every keyword errored) would otherwise read+ * "never". Report the run's own state instead.+ */+function formatLatestRun(+ run: {+ status: "pending" | "running" | "completed" | "failed";+ completedAt: string | null;+ lastCheckedAt: string | null;+ errorMessage: string | null;+ } | null,+): string {+ if (!run) return "Latest run: never";+ if (run.status === "failed")+ return `Latest run: failed — ${run.errorMessage ?? "Unknown error"}`;+ if (run.status === "completed")+ return `Latest run: ${run.completedAt ?? run.lastCheckedAt ?? "completed"}`;+ return `Latest run: ${run.status}`;+}+const inputSchema = {projectId: projectIdSchema,trackerId: z@@ -59,6 +80,7 @@ export const getRankTrackerTool = {.object({id: z.string(),lastCheckedAt: z.string().nullable(),+ completedAt: z.string().nullable(),status: z.enum(["pending", "running", "completed", "failed"]),errorMessage: z.string().nullable(),})@@ -85,7 +107,7 @@ export const getRankTrackerTool = {configs.map((c) =>- `- ${c.id} ${c.domain} loc:${c.locationCode} schedule:${c.scheduleInterval}`,+ `- ${c.id} ${c.domain} loc:${c.locationCode}${c.locationName ? ` location:"${c.locationName}"` : ""} schedule:${c.scheduleInterval}`,).join("\n");return mcpResponse({@@ -104,19 +126,14 @@ export const getRankTrackerTool = {args.projectId,);const text = [- `Tracker ${config.id} (${config.domain}):`,+ `Tracker ${config.id} (${config.domain}${config.locationName ? `, ${config.locationName}` : ""}):`,`Schedule: ${config.scheduleInterval}, devices: ${config.devices}, depth: ${config.serpDepth}`,- `Latest run: ${results.run?.lastCheckedAt ?? "never"}`,- results.run?.status === "failed"- ? `Latest run failed: ${results.run.errorMessage ?? "Unknown error"}`- : null,+ formatLatestRun(results.run),`Keywords (${results.rows.length}):`,results.rows.length === 0? "No keywords tracked yet.": formatMcpTable(results.rows, RANK_RESULT_COLUMNS),- ]- .filter((line): line is string => line !== null)- .join("\n");+ ].join("\n");return mcpResponse({text,meta: buildProjectMeta(diff --git a/src/server/mcp/tools/search-serp-locations.ts b/src/server/mcp/tools/search-serp-locations.tsnew file mode 100644index 00000000..4b3cd20f--- /dev/null+++ b/src/server/mcp/tools/search-serp-locations.ts@@ -0,0 +1,66 @@+import { z } from "zod";+import { fetchSerpLocationsForCountry } from "@/server/lib/dataforseo/serp-locations";+import { mcpResponse } from "@/server/mcp/formatters";+import { optionalMetaOutputSchema } from "@/server/mcp/output-schemas";+import { rankSerpLocations } from "@/shared/serp-location-search";++const inputSchema = {+ query: z+ .string()+ .min(1)+ .max(100)+ .describe('Place name, e.g. "Catonsville" or "Portland OR".'),+ countryCode: z+ .string()+ .regex(/^[a-zA-Z]{2}$/)+ .describe('Two-letter ISO country code, e.g. "us".'),+} as const;++type Args = z.infer<z.ZodObject<typeof inputSchema>>;++export const searchSerpLocationsTool = {+ name: "search_serp_locations",+ config: {+ title: "Search SERP locations",+ description:+ "Find the exact DataForSEO location name for local rank tracking. Returns up to 10 matches; pass the chosen `locationName` verbatim to create_rank_tracker. Uses no credits.",+ inputSchema,+ outputSchema: {+ locations: z.array(+ z.object({+ locationName: z.string(),+ locationCode: z.number(),+ locationType: z.string(),+ }),+ ),+ ...optionalMetaOutputSchema,+ },+ annotations: {+ readOnlyHint: true,+ openWorldHint: false,+ destructiveHint: false,+ },+ },+ handler: async (args: Args) => {+ const all = await fetchSerpLocationsForCountry(args.countryCode);+ const locations = rankSerpLocations(args.query, all, args.countryCode).map(+ (location) => ({+ locationName: location.locationName,+ locationCode: location.locationCode,+ locationType: location.locationType,+ }),+ );++ const text =+ locations.length === 0+ ? `No Google locations match "${args.query}" in ${args.countryCode}. Try the city name alone.`+ : locations+ .map(+ (location) =>+ `${location.locationName} (${location.locationType}, ${location.locationCode})`,+ )+ .join("\n");++ return mcpResponse({ text, structuredContent: { locations } });+ },+};diff --git a/src/server/mcp/tools/tool-text-output.test.ts b/src/server/mcp/tools/tool-text-output.test.tsindex 791b9ebd..06890f56 100644--- a/src/server/mcp/tools/tool-text-output.test.ts+++ b/src/server/mcp/tools/tool-text-output.test.ts@@ -290,6 +290,7 @@ describe("MCP tool text output (service-backed tools)", () => {run: {id: "run_1",lastCheckedAt: null,+ completedAt: null,status: "failed",errorMessage: "Provider request timed out",},@@ -303,7 +304,7 @@ describe("MCP tool text output (service-backed tools)", () => {);expect(textContent(result)).toContain(- "Latest run failed: Provider request timed out",+ "Latest run: failed — Provider request timed out",);expect(result.structuredContent).toMatchObject({results: {diff --git a/src/server/workflows/RankCheckWorkflow.test.ts b/src/server/workflows/RankCheckWorkflow.test.tsindex e17b80d5..cfafc209 100644--- a/src/server/workflows/RankCheckWorkflow.test.ts+++ b/src/server/workflows/RankCheckWorkflow.test.ts@@ -10,6 +10,8 @@ const mocks = vi.hoisted(() => ({getRunById: vi.fn(),getKeywordsForConfig: vi.fn(),updateRun: vi.fn(),+ updateConfig: vi.fn(),+ getSnapshotsForRun: vi.fn(),autumnCheck: vi.fn(),createDataforseoClient: vi.fn(),runLiveCheck: vi.fn(),@@ -161,3 +163,60 @@ describe("rank check workflow credit ceiling", () => {expect(mocks.autumnCheck).not.toHaveBeenCalled();});});++describe("rank check finalization", () => {+ beforeEach(() => {+ mocks.getConfigById.mockResolvedValue({ isActive: true });+ mocks.getRunById.mockResolvedValue({+ ...activeRun,+ keywordsTotal: 3,+ // Recorded by the batch step on the first rejected keyword.+ errorMessage: "Invalid Field: 'location_name'.",+ });+ mocks.getKeywordsForConfig.mockResolvedValue(+ Array.from({ length: 3 }, (_, index) => ({+ id: `kw_${index}`,+ keyword: `keyword ${index}`,+ })),+ );+ mocks.getSnapshotsForRun.mockResolvedValue([]);+ mocks.updateRun.mockResolvedValue(undefined);+ mocks.isHostedServerAuthMode.mockResolvedValue(true);+ mocks.autumnCheck.mockResolvedValue({ balance: { remaining: 1_000 } });+ });++ it("fails a run where no keyword produced a snapshot, keeping the recorded reason", async () => {+ // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the mocked base class does not inspect Worker constructor context+ const workflow = new RankCheckWorkflow({} as ExecutionContext, {} as Env);++ await workflow.run(+ {+ instanceId: "run_1",+ timestamp: new Date(),+ payload: {+ runId: "run_1",+ configId: "config_1",+ billingCustomer,+ projectId: "project_1",+ domain: "example.com",+ locationCode: 2840,+ languageCode: "en",+ devices: "desktop",+ serpDepth: 10,+ trigger: "manual",+ },+ },+ // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- workflow steps are executed directly by the pgStep mock+ {} as WorkflowStep,+ );++ expect(mocks.updateRun).toHaveBeenCalledWith(+ "run_1",+ expect.objectContaining({+ status: "failed",+ errorMessage: "Invalid Field: 'location_name'.",+ }),+ );+ expect(mocks.updateConfig).not.toHaveBeenCalled();+ });+});diff --git a/src/server/workflows/RankCheckWorkflow.ts b/src/server/workflows/RankCheckWorkflow.tsindex f056ee7b..50becfb7 100644--- a/src/server/workflows/RankCheckWorkflow.ts+++ b/src/server/workflows/RankCheckWorkflow.ts@@ -168,29 +168,37 @@ async function finalizeRankCheckRun(input: {const keywordsTotal = run.keywordsTotal || keywordsChecked;const incompleteCount = keywordsTotal - keywordsChecked;- let errorMessage: string | undefined;- if (input.batchError) {- errorMessage = `Completed ${keywordsChecked} of ${keywordsTotal} keyword(s). Error: ${input.batchError}`;- } else if (incompleteCount > 0) {- errorMessage = `${incompleteCount} keyword(s) could not be checked`;- }+ // Batch steps record the first per-keyword rejection on the run as it+ // happens, so a failed run shows the vendor's reason rather than a count.+ const keywordError = run.errorMessage ?? input.batchError;+ const status =+ keywordsChecked === 0 && keywordsTotal > 0 ? "failed" : "completed";+ const errorMessage =+ status === "failed"+ ? (keywordError ?? "No keywords could be checked.")+ : incompleteCount > 0+ ? `Checked ${keywordsChecked} of ${keywordsTotal} keyword(s)${keywordError ? `: ${keywordError}` : ""}`+ : null;// Flipping status away from 'pending'/'running' is what releases the// partial-index slot for the next run.await RankTrackingRepository.updateRun(input.runId, {- status: "completed",+ status,keywordsChecked,completedAt: nowIso,- ...(errorMessage ? { errorMessage } : {}),+ errorMessage,});- // Clear any previous skip reason on success.+ // Clear any previous skip reason on success. A failed run must not advance+ // lastCheckedAt — nothing was actually checked.// Note: nextCheckAt is NOT set here — the cron handler advances it eagerly// before starting the workflow to prevent retry storms.- await RankTrackingRepository.updateConfig(input.configId, input.projectId, {- lastCheckedAt: nowIso,- lastSkipReason: null,- });+ if (status === "completed") {+ await RankTrackingRepository.updateConfig(input.configId, input.projectId, {+ lastCheckedAt: nowIso,+ lastSkipReason: null,+ });+ }// One-line summary per run so fallback rates are visible in Workers Logs.// Keys match the PostHog event properties for log/event correlation.@@ -202,7 +210,7 @@ async function finalizeRankCheckRun(input: {? ` error="${errorMessage.replace(/\s+/g, " ").slice(0, 200)}"`: "";console.log(- `[rank-check] ${input.runId} completed org=${input.billingCustomer.organizationId} project=${input.projectId} trigger=${input.trigger} keywords=${keywordsChecked}/${keywordsTotal}${queueSummary}${errorSummary}`,+ `[rank-check] ${input.runId} ${status} org=${input.billingCustomer.organizationId} project=${input.projectId} trigger=${input.trigger} keywords=${keywordsChecked}/${keywordsTotal}${queueSummary}${errorSummary}`,);await captureServerEvent({@@ -211,7 +219,7 @@ async function finalizeRankCheckRun(input: {organizationId: input.billingCustomer.organizationId,properties: {project_id: input.projectId,- status: "completed",+ status,trigger: input.trigger,keywords_checked: keywordsChecked,...(input.queueStatsdiff --git a/src/server/workflows/rankCheckPaths.ts b/src/server/workflows/rankCheckPaths.tsindex 05038765..06f66c9f 100644--- a/src/server/workflows/rankCheckPaths.ts+++ b/src/server/workflows/rankCheckPaths.ts@@ -101,6 +101,7 @@ async function checkBatchLive(),);const results: RankCheckResultWithDevice[] = [];+ let firstError: string | null = null;settled.forEach((outcome, index) => {if (outcome.status === "fulfilled") {results.push(outcome.value);@@ -109,6 +110,7 @@ async function checkBatchLive(const reason: unknown = outcome.reason;const code = reason instanceof AppError ? reason.code : "UNKNOWN";const message = reason instanceof Error ? reason.message : String(reason);+ firstError ??= message;// DataForSEO erring on its own side is a provider flake, not our bug: the// keyword just misses this run and finalize reports it to the user. Every// other rejection (no credits, bad API key) is ours and stays at error.@@ -118,6 +120,9 @@ async function checkBatchLive(`[rank-check] ${ctx.runId} live call failed (${code}) keyword="${task.keyword}" device=${task.device}: ${message}`,);});+ if (firstError) {+ await RankTrackingRepository.setRunErrorIfEmpty(ctx.runId, firstError);+ }if (results.length > 0) {await RankTrackingRepository.insertSnapshots(mapResultsToSnapshotRows(ctx.runId, results),@@ -207,6 +212,7 @@ async function collectQueuedRound(const completed: RankCheckResultWithDevice[] = [];const stillPending: PostedRankCheckTask[] = [];const failed: PostedRankCheckTask[] = [];+ let firstError: string | null = null;for (let i = 0; i < tasks.length; i += TASK_GET_CONCURRENCY) {const chunk = tasks.slice(i, i + TASK_GET_CONCURRENCY);@@ -235,6 +241,7 @@ async function collectQueuedRound(console.warn(`[rank-check] ${ctx.runId} task ${task.taskId} failed: ${result.value.message}`,);+ firstError ??= result.value.message;failed.push(task);} else {completed.push({ ...result.value.result, device: task.device });@@ -242,6 +249,9 @@ async function collectQueuedRound(});}+ if (firstError) {+ await RankTrackingRepository.setRunErrorIfEmpty(ctx.runId, firstError);+ }if (completed.length > 0) {await RankTrackingRepository.insertSnapshots(mapResultsToSnapshotRows(ctx.runId, completed),diff --git a/src/serverFunctions/serp-locations.ts b/src/serverFunctions/serp-locations.tsindex 8356553e..708a75ae 100644--- a/src/serverFunctions/serp-locations.ts+++ b/src/serverFunctions/serp-locations.ts@@ -2,6 +2,7 @@ import { createServerFn } from "@tanstack/react-start";import { z } from "zod";import { requireAuthenticatedContext } from "@/serverFunctions/middleware";import { fetchSerpLocationsForCountry } from "@/server/lib/dataforseo/serp-locations";+import { rankSerpLocations } from "@/shared/serp-location-search";/** ISO 3166-1 alpha-2, e.g. "us" — DataForSEO rejects country names. */const countryCodeField = z.string().regex(/^[a-z]{2}$/i);@@ -16,10 +17,7 @@ export const searchSerpLocations = createServerFn({ method: "POST" }).validator(searchSerpLocationsSchema).handler(async ({ data }) => {const all = await fetchSerpLocationsForCountry(data.countryCode);- const needle = data.query.trim().toLowerCase();- return all- .filter((loc) => loc.displayLabel.toLowerCase().includes(needle))- .slice(0, 10);+ return rankSerpLocations(data.query, all, data.countryCode);});/**diff --git a/src/shared/serp-location-search.test.ts b/src/shared/serp-location-search.test.tsnew file mode 100644index 00000000..53406e4f--- /dev/null+++ b/src/shared/serp-location-search.test.ts@@ -0,0 +1,54 @@+import { describe, expect, it } from "vitest";+import { rankSerpLocations } from "./serp-location-search";++const locations = [+ { locationName: "South Portland,Maine,United States", locationType: "City" },+ {+ locationName: "Portland, OR,Oregon,United States",+ locationType: "DMA Region",+ },+ { locationName: "Portland,Oregon,United States", locationType: "City" },+ { locationName: "Portland,Maine,United States", locationType: "City" },+ { locationName: "Portland,Texas,United States", locationType: "City" },+ { locationName: "Catonsville,Maryland,United States", locationType: "City" },+ { locationName: "New City,New York,United States", locationType: "City" },+ { locationName: "New York,New York,United States", locationType: "City" },+ { locationName: "La Crosse,Wisconsin,United States", locationType: "City" },+];++describe("rankSerpLocations", () => {+ it("ranks exact first-segment cities above prefixed names and DMA regions", () => {+ const names = rankSerpLocations("Portland", locations).map(+ (location) => location.locationName,+ );++ expect(names.slice(0, 2)).toEqual([+ "Portland,Maine,United States",+ "Portland,Oregon,United States",+ ]);+ expect(names.indexOf("South Portland,Maine,United States")).toBeGreaterThan(+ names.indexOf("Portland, OR,Oregon,United States"),+ );+ });++ it("expands a US state abbreviation so 'Catonsville MD' matches the canonical row", () => {+ expect(rankSerpLocations("Catonsville MD", locations, "us")).toEqual([+ {+ locationName: "Catonsville,Maryland,United States",+ locationType: "City",+ },+ ]);+ });++ it("prefers the place whose name is the whole query over first-token matches", () => {+ expect(rankSerpLocations("New York", locations)[0]?.locationName).toBe(+ "New York,New York,United States",+ );+ });++ it("never reads the place name itself as a state abbreviation", () => {+ expect(+ rankSerpLocations("La Crosse", locations, "us")[0]?.locationName,+ ).toBe("La Crosse,Wisconsin,United States");+ });+});diff --git a/src/shared/serp-location-search.ts b/src/shared/serp-location-search.tsnew file mode 100644index 00000000..ab5aa46c--- /dev/null+++ b/src/shared/serp-location-search.ts@@ -0,0 +1,185 @@+/**+ * Rank a country's SERP location registry against a free-form place query+ * ("Catonsville MD", "Portland OR"). DataForSEO matches `location_name`+ * verbatim, so users need the canonical row, not a substring scan: a plain+ * `includes` filter buries "Portland,Oregon,United States" under every+ * "…,Portland,…" row that happens to sort earlier in the registry.+ *+ * The folding, abbreviation and type-rank primitives are shared with the+ * repair script's fuzzy matcher (scripts/serp-location-match.ts) so both+ * agree on what a name means.+ */++interface RankableSerpLocation {+ locationName: string;+ locationType: string;+}++/**+ * Region abbreviations users write after a city name, per country. Keyed by+ * ISO country so "Rio de Janeiro" in Brazil never reads "de" as Delaware.+ */+export const REGION_ABBREVIATIONS: Record<string, Record<string, string>> = {+ us: {+ al: "Alabama",+ ak: "Alaska",+ az: "Arizona",+ ar: "Arkansas",+ ca: "California",+ co: "Colorado",+ ct: "Connecticut",+ de: "Delaware",+ fl: "Florida",+ ga: "Georgia",+ hi: "Hawaii",+ id: "Idaho",+ il: "Illinois",+ in: "Indiana",+ ia: "Iowa",+ ks: "Kansas",+ ky: "Kentucky",+ la: "Louisiana",+ me: "Maine",+ md: "Maryland",+ ma: "Massachusetts",+ mi: "Michigan",+ mn: "Minnesota",+ ms: "Mississippi",+ mo: "Missouri",+ mt: "Montana",+ ne: "Nebraska",+ nv: "Nevada",+ nh: "New Hampshire",+ nj: "New Jersey",+ nm: "New Mexico",+ ny: "New York",+ nc: "North Carolina",+ nd: "North Dakota",+ oh: "Ohio",+ ok: "Oklahoma",+ or: "Oregon",+ pa: "Pennsylvania",+ ri: "Rhode Island",+ sc: "South Carolina",+ sd: "South Dakota",+ tn: "Tennessee",+ tx: "Texas",+ ut: "Utah",+ vt: "Vermont",+ va: "Virginia",+ wa: "Washington",+ wv: "West Virginia",+ wi: "Wisconsin",+ wy: "Wyoming",+ dc: "District of Columbia",+ },+ ca: {+ ab: "Alberta",+ bc: "British Columbia",+ mb: "Manitoba",+ nb: "New Brunswick",+ nl: "Newfoundland and Labrador",+ ns: "Nova Scotia",+ nt: "Northwest Territories",+ nu: "Nunavut",+ on: "Ontario",+ pe: "Prince Edward Island",+ qc: "Quebec",+ sk: "Saskatchewan",+ yt: "Yukon",+ },+ au: {+ nsw: "New South Wales",+ vic: "Victoria",+ qld: "Queensland",+ sa: "South Australia",+ tas: "Tasmania",+ act: "Australian Capital Territory",+ },+};++/**+ * Registry rows a user could plausibly mean by a place name, most specific+ * first. Postal codes, airports and universities are absent on purpose: they+ * are never what "City, ST" means.+ */+export const LOCATION_TYPE_RANK: Record<string, number> = {+ City: 0,+ Municipality: 1,+ "City Region": 2,+ Borough: 2,+ County: 3,+ State: 4,+ Province: 4,+ Region: 4,+ Country: 5,+ "DMA Region": 6,+ Neighborhood: 7,+ District: 7,+};++/** Lowercase, strip accents, collapse whitespace. */+export function foldLocationText(value: string): string {+ return value+ .normalize("NFD")+ .replace(/\p{M}/gu, "")+ .toLowerCase()+ .replace(/\s+/g, " ")+ .trim();+}++/**+ * "Portland OR" → ["portland", "oregon"]. Abbreviations expand only for the+ * given country and never on the first token: "La Crosse" and "De Pere" are+ * place names, not states.+ */+function tokenize(query: string, countryCode: string | undefined): string[] {+ const tokens = foldLocationText(query)+ .split(/[\s,]+/)+ .filter(Boolean);+ const abbreviations = REGION_ABBREVIATIONS[countryCode?.toLowerCase() ?? ""];+ if (!abbreviations) return tokens;+ return tokens.map((token, index) => {+ const region = index > 0 ? abbreviations[token] : undefined;+ return region ? foldLocationText(region) : token;+ });+}++export function rankSerpLocations<T extends RankableSerpLocation>(+ query: string,+ locations: readonly T[],+ countryCode?: string,+): T[] {+ const tokens = tokenize(query, countryCode);+ if (tokens.length === 0) return [];+ const phrase = tokens.join(" ");+ const head = tokens[0];++ const scored: { location: T; score: number; folded: string }[] = [];+ for (const location of locations) {+ const folded = foldLocationText(location.locationName);+ // Multi-word expansions ("new york") never survive a whitespace split, so+ // match each token against the whole name.+ if (!tokens.every((token) => folded.includes(token))) continue;+ const comma = folded.indexOf(",");+ const place = comma < 0 ? folded : folded.slice(0, comma).trim();+ const score =+ place === phrase+ ? 0+ : place === head+ ? 1+ : place.startsWith(head)+ ? 2+ : 3;+ scored.push({ location, score, folded });+ }++ scored.sort(+ (a, b) =>+ a.score - b.score ||+ (LOCATION_TYPE_RANK[a.location.locationType] ?? 9) -+ (LOCATION_TYPE_RANK[b.location.locationType] ?? 9) ||+ (a.folded < b.folded ? -1 : a.folded > b.folded ? 1 : 0),+ );+ return scored.slice(0, 10).map((entry) => entry.location);+}diff --git a/vitest.config.ts b/vitest.config.tsindex 33de7e05..6217b4da 100644--- a/vitest.config.ts+++ b/vitest.config.ts@@ -5,7 +5,7 @@ export default defineConfig({plugins: [tsConfigPaths()],test: {environment: "node",- include: ["src/**/*.test.ts"],+ include: ["src/**/*.test.ts", "scripts/**/*.test.ts"],restoreMocks: true,clearMocks: true,server: {