admin/metatron-open-seo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: configurable default market for location/language fallbacks (#72)

Browse Source
This commit is contained in:
bookingseo 2026-07-16 21:46:49 +07:00 committed by GitHub
parent c1121bdcab
commit 0f08437cd0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
72 changed files with 1490 additions and 363 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
e2e/fixtures/keyword-research-fixtures.ts
View File

@ -1,5 +1,5 @@
import type { KeywordResearchRow } from "@/types/keywords";
import type { ResearchKeywordsInput } from "@/types/schemas/keywords";
import type { ResolvedResearchKeywordsInput } from "@/types/schemas/keywords";
const MONTHLY_SEARCHES = [
{ year: 2025, month: 4, searchVolume: 1200 },
@ -33,7 +33,7 @@ function makeRow(
};
}
export function getKeywordResearchFixture(data: ResearchKeywordsInput) {
export function getKeywordResearchFixture(data: ResolvedResearchKeywordsInput) {
const seedKeyword = data.keywords[0] ?? "keyword research";
const rows = [
makeRow(seedKeyword, 0, {

79
src/client/features/domain/DomainOverviewPage.tsx
View File

@ -8,9 +8,7 @@ import {
type DomainSearchParams,
} from "@/types/schemas/domain";
import {
DEFAULT_LOCATION_CODE,
LOCATIONS,
getLanguageCode,
isLabsLocationCode,
} from "@/client/features/keywords/locations";
import { useDomainSearchHistory } from "@/client/hooks/useDomainSearchHistory";
@ -80,10 +78,13 @@ function getSortSearchUpdate(
};
}
function getLocationSearchUpdate(nextLocationCode: number): DomainSearchUpdate {
function getLocationSearchUpdate(
nextLocationCode: number,
defaultLocationCode: number,
): DomainSearchUpdate {
return {
loc:
nextLocationCode === DEFAULT_LOCATION_CODE ? undefined : nextLocationCode,
nextLocationCode === defaultLocationCode ? undefined : nextLocationCode,
page: undefined,
};
}
@ -122,11 +123,12 @@ function getTabSearchUpdate(
function getHistorySearchUpdate(
item: DomainSearchHistoryItem,
defaultLocationCode: number,
): DomainSearchUpdate {
const historyLocation =
item.locationCode != null && isLabsLocationCode(item.locationCode)
? item.locationCode
: DEFAULT_LOCATION_CODE;
: defaultLocationCode;
return {
...buildDomainFiltersClearSearchUpdate(),
@ -135,8 +137,7 @@ function getHistorySearchUpdate(
sort: toSortSearchParam(item.sort),
order: undefined,
tab: item.tab === "keywords" ? undefined : item.tab,
loc:
historyLocation === DEFAULT_LOCATION_CODE ? undefined : historyLocation,
loc: historyLocation === defaultLocationCode ? undefined : historyLocation,
size: undefined,
};
}
@ -148,6 +149,7 @@ function getSearchSubmitUpdate({
locationCode,
currentOrder,
activeTab,
defaultLocationCode,
}: {
domain: string;
subdomains: boolean;
@ -155,6 +157,7 @@ function getSearchSubmitUpdate({
locationCode: number;
currentOrder: SortOrder;
activeTab: DomainActiveTab;
defaultLocationCode: number;
}): DomainSearchUpdate {
return {
...buildDomainFiltersClearSearchUpdate(),
@ -163,7 +166,7 @@ function getSearchSubmitUpdate({
sort: toSortSearchParam(sort),
order: toSortOrderSearchParam(sort, currentOrder),
tab: activeTab === "keywords" ? undefined : activeTab,
loc: locationCode === DEFAULT_LOCATION_CODE ? undefined : locationCode,
loc: locationCode === defaultLocationCode ? undefined : locationCode,
size: undefined,
};
}
@ -205,9 +208,14 @@ function useDomainOverviewState({
const applyLocationChange = useCallback(
(nextLocationCode: number) => {
setSearchParams(getLocationSearchUpdate(nextLocationCode));
setSearchParams(
getLocationSearchUpdate(
nextLocationCode,
routeState.defaultLocationCode,
),
);
},
[setSearchParams],
[routeState.defaultLocationCode, setSearchParams],
);
const handleSortColumnClick = useCallback(
@ -246,21 +254,21 @@ function useDomainOverviewState({
const handleHistorySelect = useCallback(
(item: DomainSearchHistoryItem) => {
setSearchParams(getHistorySearchUpdate(item));
setSearchParams(
getHistorySearchUpdate(item, routeState.defaultLocationCode),
);
},
[setSearchParams],
[routeState.defaultLocationCode, setSearchParams],
);
const languageCode = getLanguageCode(routeState.locationCode);
const overviewQuery = useDomainOverviewQuery({
projectId,
domain: routeState.domain,
includeSubdomains: routeState.subdomains,
locationCode: routeState.locationCode,
languageCode,
locationCode: routeState.sentLocationCode,
});
const overview = overviewQuery.data ?? null;
const isLoading = overviewQuery.isLoading;
const isLoading = routeState.domain.trim() !== "" && overviewQuery.isLoading;
const controlsForm = useForm({
defaultValues: {
@ -290,6 +298,7 @@ function useDomainOverviewState({
locationCode: value.locationCode,
currentOrder: routeState.order,
activeTab: routeState.tab,
defaultLocationCode: routeState.defaultLocationCode,
}),
);
},
@ -389,7 +398,6 @@ function useDomainOverviewState({
history,
historyLoaded,
removeHistoryItem,
languageCode,
setSearchParams,
applySort,
applyLocationChange,
@ -412,16 +420,20 @@ export function DomainOverviewPage({
navigate,
onShowRecentSearches,
}: Props) {
const state = useDomainOverviewState({ navigate, routeState, projectId });
const state = useDomainOverviewState({
navigate,
routeState,
projectId,
});
const urlTabInput = useMemo<SearchTabInput | null>(() => {
if (routeState.domain.trim() === "") return null;
return {
type: "domain",
domain: routeState.domain,
subdomains: routeState.subdomains,
locationCode: routeState.locationCode,
locationCode: routeState.sentLocationCode,
};
}, [routeState.domain, routeState.locationCode, routeState.subdomains]);
}, [routeState.domain, routeState.sentLocationCode, routeState.subdomains]);
const navigateToSearchTab = useCallback(
(input: SearchTabInput | null) => {
@ -443,10 +455,7 @@ export function DomainOverviewPage({
order: undefined,
tab: undefined,
page: undefined,
loc:
input.locationCode === DEFAULT_LOCATION_CODE
? undefined
: input.locationCode,
loc: input.locationCode,
size: undefined,
}),
replace: true,
@ -458,14 +467,18 @@ export function DomainOverviewPage({
const searchTabs = useSearchTabNavigation({
storageKey: `domain:${projectId}`,
urlInput: urlTabInput,
getLabel: useCallback((input) => {
if (input.type !== "domain") return "";
const locationSuffix =
input.locationCode === DEFAULT_LOCATION_CODE
? ""
: ` ${LOCATIONS[input.locationCode] ?? input.locationCode}`;
return `${input.domain}${locationSuffix}`;
}, []),
getLabel: useCallback(
(input) => {
if (input.type !== "domain") return "";
const locationSuffix =
input.locationCode == null ||
input.locationCode === routeState.defaultLocationCode
? ""
: ` ${LOCATIONS[input.locationCode] ?? input.locationCode}`;
return `${input.domain}${locationSuffix}`;
},
[routeState.defaultLocationCode],
),
navigateToInput: navigateToSearchTab,
});
@ -623,7 +636,6 @@ export function DomainOverviewPage({
key="keywords"
projectId={projectId}
domain={state.overview.domain}
languageCode={state.languageCode}
routeState={routeState}
canSaveKeywords={state.canSaveKeywords}
setSearchParams={state.setSearchParams}
@ -636,7 +648,6 @@ export function DomainOverviewPage({
key="pages"
projectId={projectId}
domain={state.overview.domain}
languageCode={state.languageCode}
routeState={routeState}
setSearchParams={state.setSearchParams}
onSortClick={state.handleSortColumnClick}

11
src/client/features/domain/components/KeywordsTab.tsx
View File

@ -65,7 +65,6 @@ const KEYWORD_RANGE_FILTERS = [
type Props = {
projectId: string;
domain: string;
languageCode: string;
routeState: DomainOverviewRouteState;
canSaveKeywords: boolean;
setSearchParams: (updates: SearchUpdate) => void;
@ -77,7 +76,6 @@ type Props = {
export function KeywordsTab({
projectId,
domain,
languageCode,
routeState,
canSaveKeywords,
setSearchParams,
@ -106,8 +104,7 @@ export function KeywordsTab({
projectId,
domain,
includeSubdomains: routeState.subdomains,
locationCode: routeState.locationCode,
languageCode,
locationCode: routeState.sentLocationCode,
page: routeState.page,
pageSize: routeState.pageSize,
sortMode: routeState.sort,
@ -159,13 +156,11 @@ export function KeywordsTab({
filteredKeywords: rows,
save: saveMutation.mutate,
projectId,
locationCode: routeState.locationCode,
languageCode,
locationCode: routeState.sentLocationCode,
});
}, [
languageCode,
projectId,
routeState.locationCode,
routeState.sentLocationCode,
rows,
saveMutation.mutate,
selectedKeywords,

5
src/client/features/domain/components/PagesTab.tsx
View File

@ -55,7 +55,6 @@ const PAGE_RANGE_FILTERS = [
type Props = {
projectId: string;
domain: string;
languageCode: string;
routeState: DomainOverviewRouteState;
setSearchParams: (updates: SearchUpdate) => void;
onSortClick: (sort: DomainSortMode) => void;
@ -66,7 +65,6 @@ type Props = {
export function PagesTab({
projectId,
domain,
languageCode,
routeState,
setSearchParams,
onSortClick,
@ -98,8 +96,7 @@ export function PagesTab({
projectId,
domain,
includeSubdomains: routeState.subdomains,
locationCode: routeState.locationCode,
languageCode,
locationCode: routeState.sentLocationCode,
page: routeState.page,
pageSize: routeState.pageSize,
sortMode: routeState.sort,

8
src/client/features/domain/domainActions.ts
View File

@ -6,8 +6,7 @@ import type { KeywordRow } from "@/client/features/domain/types";
type SaveMutation = (payload: {
projectId: string;
keywords: string[];
locationCode: number;
languageCode: string;
locationCode?: number;
metrics?: Array<{
keyword: string;
searchVolume?: number | null;
@ -27,14 +26,12 @@ export function saveSelectedKeywords({
save,
projectId,
locationCode,
languageCode,
}: {
selectedKeywords: Set<string>;
filteredKeywords: KeywordRow[];
save: (payload: Parameters<SaveMutation>[0], opts?: SaveOptions) => void;
projectId: string;
locationCode: number;
languageCode: string;
locationCode?: number;
}) {
if (selectedKeywords.size === 0) {
toast.error("Select at least one keyword first");
@ -49,7 +46,6 @@ export function saveSelectedKeywords({
projectId,
keywords: [...selectedKeywords],
locationCode,
languageCode,
metrics: selectedRows.map((row) => ({
keyword: row.keyword,
searchVolume: row.searchVolume,

48
src/client/features/domain/domainRouteState.test.ts Normal file
View File

@ -0,0 +1,48 @@
import { describe, expect, it } from "vitest";
import { getDomainRouteState } from "./domainRouteState";
describe("getDomainRouteState", () => {
it("uses a Labs-backed project market when the URL omits loc", () => {
const state = getDomainRouteState(
{},
{ locationCode: 2704, languageCode: "vi" },
);
expect(state.defaultLocationCode).toBe(2704);
expect(state.locationCode).toBe(2704);
expect(state.sentLocationCode).toBeUndefined();
});
it("keeps an explicit Labs-backed URL location", () => {
const state = getDomainRouteState(
{ loc: 2840 },
{ locationCode: 2704, languageCode: "vi" },
);
expect(state.defaultLocationCode).toBe(2704);
expect(state.locationCode).toBe(2840);
expect(state.sentLocationCode).toBe(2840);
});
it("falls back to US for a Google-Ads-only project market", () => {
const state = getDomainRouteState(
{},
{ locationCode: 2352, languageCode: "is" },
);
expect(state.defaultLocationCode).toBe(2840);
expect(state.locationCode).toBe(2840);
expect(state.sentLocationCode).toBeUndefined();
});
it("ignores a Google-Ads-only URL location", () => {
const state = getDomainRouteState(
{ loc: 2352 },
{ locationCode: 2704, languageCode: "vi" },
);
expect(state.defaultLocationCode).toBe(2704);
expect(state.locationCode).toBe(2704);
expect(state.sentLocationCode).toBe(2352);
});
});

12
src/client/features/domain/domainRouteState.ts
View File

@ -6,6 +6,7 @@ import {
DEFAULT_LOCATION_CODE,
isLabsLocationCode,
} from "@/client/features/keywords/locations";
import type { ProjectMarket } from "@/client/features/projects/types";
import {
EMPTY_DOMAIN_FILTERS,
type DomainActiveTab,
@ -28,7 +29,9 @@ export type DomainOverviewRouteState = {
sort: DomainSortMode;
order: SortOrder;
tab: DomainActiveTab;
defaultLocationCode: number;
locationCode: number;
sentLocationCode: number | undefined;
page: number;
pageSize: number;
appliedFilters: DomainFilterValues;
@ -44,13 +47,18 @@ function numberToFilterString(value: number | undefined): string {
export function getDomainRouteState(
search: DomainSearchParams,
projectMarket?: ProjectMarket,
): DomainOverviewRouteState {
const normalizedSort = toSortMode(search.sort ?? null) ?? "traffic";
const defaultLocationCode =
projectMarket && isLabsLocationCode(projectMarket.locationCode)
? projectMarket.locationCode
: DEFAULT_LOCATION_CODE;
// Domain analytics is Labs-backed; Google-Ads-only countries aren't valid.
const normalizedLocationCode =
search.loc != null && isLabsLocationCode(search.loc)
? search.loc
: DEFAULT_LOCATION_CODE;
: defaultLocationCode;
return {
domain: search.domain ?? "",
@ -58,7 +66,9 @@ export function getDomainRouteState(
sort: normalizedSort,
order: resolveSortOrder(normalizedSort, toSortOrder(search.order ?? null)),
tab: search.tab ?? "keywords",
defaultLocationCode,
locationCode: normalizedLocationCode,
sentLocationCode: search.loc,
page: search.page != null && search.page > 0 ? search.page : 1,
pageSize: search.size ?? DEFAULT_DOMAIN_KEYWORDS_PAGE_SIZE,
appliedFilters: {

6
src/client/features/domain/hooks/useDomainKeywordsQuery.ts
View File

@ -12,8 +12,7 @@ type DomainKeywordsQueryInput = {
projectId: string;
domain: string;
includeSubdomains: boolean;
locationCode: number;
languageCode: string;
locationCode: number | undefined;
page: number;
pageSize: number;
sortMode: DomainSortMode;
@ -60,7 +59,6 @@ export function useDomainKeywordsQuery(input: DomainKeywordsQueryInput) {
input.domain,
input.includeSubdomains,
input.locationCode,
input.languageCode,
input.page,
input.pageSize,
input.sortMode,
@ -71,7 +69,6 @@ export function useDomainKeywordsQuery(input: DomainKeywordsQueryInput) {
filtersPayload,
input.domain,
input.includeSubdomains,
input.languageCode,
input.locationCode,
input.page,
input.pageSize,
@ -98,7 +95,6 @@ export function useDomainKeywordsQuery(input: DomainKeywordsQueryInput) {
domain: input.domain,
includeSubdomains: input.includeSubdomains,
locationCode: input.locationCode,
languageCode: input.languageCode,
page: input.page,
pageSize: input.pageSize,
sortMode: input.sortMode,

5
src/client/features/domain/hooks/useDomainOverviewQuery.ts
View File

@ -5,8 +5,7 @@ type Input = {
projectId: string;
domain: string;
includeSubdomains: boolean;
locationCode: number;
languageCode: string;
locationCode: number | undefined;
};
export function useDomainOverviewQuery(input: Input) {
@ -20,7 +19,6 @@ export function useDomainOverviewQuery(input: Input) {
trimmedDomain,
input.includeSubdomains,
input.locationCode,
input.languageCode,
],
queryFn: () =>
getDomainOverview({
@ -29,7 +27,6 @@ export function useDomainOverviewQuery(input: Input) {
domain: trimmedDomain,
includeSubdomains: input.includeSubdomains,
locationCode: input.locationCode,
languageCode: input.languageCode,
},
}),
staleTime: 5 * 60_000,

6
src/client/features/domain/hooks/useDomainPagesQuery.ts
View File

@ -13,8 +13,7 @@ type DomainPagesQueryInput = {
projectId: string;
domain: string;
includeSubdomains: boolean;
locationCode: number;
languageCode: string;
locationCode: number | undefined;
page: number;
pageSize: number;
sortMode: DomainSortMode;
@ -32,7 +31,6 @@ export function useDomainPagesQuery(input: DomainPagesQueryInput) {
input.domain,
input.includeSubdomains,
input.locationCode,
input.languageCode,
input.page,
input.pageSize,
pageSortMode,
@ -43,7 +41,6 @@ export function useDomainPagesQuery(input: DomainPagesQueryInput) {
input.appliedFilters,
input.domain,
input.includeSubdomains,
input.languageCode,
input.locationCode,
input.page,
input.pageSize,
@ -70,7 +67,6 @@ export function useDomainPagesQuery(input: DomainPagesQueryInput) {
domain: input.domain,
includeSubdomains: input.includeSubdomains,
locationCode: input.locationCode,
languageCode: input.languageCode,
page: input.page,
pageSize: input.pageSize,
sortMode: pageSortMode,

3
src/client/features/domain/mutations.ts
View File

@ -12,8 +12,7 @@ export function useSaveKeywordsMutation({
mutationFn: (data: {
projectId: string;
keywords: string[];
locationCode: number;
languageCode: string;
locationCode?: number;
metrics?: Array<{
keyword: string;
searchVolume?: number | null;

2
src/client/features/keywords/hooks/useKeywordControlsForm.ts
View File

@ -13,7 +13,7 @@ import { parseKeywordInput } from "@/client/features/keywords/state/keywordContr
type KeywordTabValidationInput = {
keyword: string;
locationCode: number;
locationCode: number | undefined;
resultLimit: ResultLimit;
mode: KeywordMode;
clickstream: boolean;

35
src/client/features/keywords/hooks/useKeywordResearchData.test.ts Normal file
View File

@ -0,0 +1,35 @@
import { describe, expect, it, vi } from "vitest";
// The hook module pulls in the server functions it calls, whose graph reaches
// Workers-only bindings that don't resolve outside workerd.
vi.mock("cloudflare:workers", () => ({ env: {} }));
import { buildKeywordResearchRequest } from "./useKeywordResearchData";
const baseInput = {
projectId: "project_1",
keywordInput: "technical seo",
locationCode: 2704,
resultLimit: 150 as const,
mode: "auto" as const,
clickstream: false,
};
describe("buildKeywordResearchRequest", () => {
it("carries an explicitly selected location without a language", () => {
const request = buildKeywordResearchRequest(baseInput);
expect(request).toMatchObject({ locationCode: 2704 });
expect(request).not.toHaveProperty("languageCode");
});
it("leaves the location undefined for the server to resolve", () => {
const request = buildKeywordResearchRequest({
...baseInput,
locationCode: undefined,
});
expect(request).toMatchObject({ locationCode: undefined });
expect(request).not.toHaveProperty("languageCode");
});
});

31
src/client/features/keywords/hooks/useKeywordResearchData.ts
View File

@ -2,8 +2,7 @@ import { useEffect, useMemo, useRef } from "react";
import { useQuery } from "@tanstack/react-query";
import { getStandardErrorMessage } from "@/client/lib/error-messages";
import { captureClientEvent } from "@/client/lib/posthog";
import { LOCATIONS, getLanguageCode } from "@/client/features/keywords/utils";
import { DEFAULT_LOCATION_CODE } from "@/client/features/keywords/locations";
import { LOCATIONS } from "@/client/features/keywords/utils";
import { parseKeywordInput } from "@/client/features/keywords/state/keywordControllerActions";
import { researchKeywords } from "@/serverFunctions/keywords";
import type {
@ -18,21 +17,24 @@ type AddSearchFn = (
locationName: string,
) => void;
type KeywordResearchQueryInput = {
type KeywordResearchRequestInput = {
projectId: string;
keywordInput: string;
locationCode: number;
locationCode: number | undefined;
resultLimit: ResultLimit;
mode: KeywordMode;
clickstream: boolean;
};
type KeywordResearchQueryInput = KeywordResearchRequestInput & {
displayedLocationCode: number;
};
type KeywordResearchRequest = {
projectId: string;
keywords: string[];
seedKeyword: string;
locationCode: number;
languageCode: string;
locationCode: number | undefined;
resultLimit: ResultLimit;
mode: KeywordMode;
clickstream: boolean;
@ -41,7 +43,7 @@ type KeywordResearchRequest = {
export const KEYWORD_RESEARCH_STALE_TIME_MS = 24 * 60 * 60 * 1000;
export function buildKeywordResearchRequest(
input: KeywordResearchQueryInput,
input: KeywordResearchRequestInput,
): KeywordResearchRequest | null {
const keywords = parseKeywordInput(input.keywordInput);
const seedKeyword = keywords[0] ?? "";
@ -52,7 +54,6 @@ export function buildKeywordResearchRequest(
keywords,
seedKeyword,
locationCode: input.locationCode,
languageCode: getLanguageCode(input.locationCode),
resultLimit: input.resultLimit,
mode: input.mode,
clickstream: input.clickstream,
@ -68,7 +69,6 @@ export function buildKeywordResearchQueryKey(
request.projectId,
request.keywords,
request.locationCode,
request.languageCode,
request.resultLimit,
request.mode,
request.clickstream,
@ -82,7 +82,6 @@ export function keywordResearchQueryFn(request: KeywordResearchRequest) {
projectId: request.projectId,
keywords: request.keywords,
locationCode: request.locationCode,
languageCode: request.languageCode,
resultLimit: request.resultLimit,
mode: request.mode,
clickstream: request.clickstream,
@ -96,6 +95,7 @@ export function useKeywordResearchData(
) {
const {
clickstream,
displayedLocationCode,
keywordInput,
locationCode,
mode,
@ -144,7 +144,7 @@ export function useKeywordResearchData(
handledSuccessKeyRef.current = queryKeyString;
captureClientEvent("keyword_research:search_complete", {
location_code: request.locationCode,
location_code: displayedLocationCode,
search_mode: request.mode,
clickstream: request.clickstream,
result_count: researchQuery.data.rows.length,
@ -152,18 +152,19 @@ export function useKeywordResearchData(
addSearch(
request.seedKeyword,
request.locationCode,
LOCATIONS[request.locationCode] || "Unknown",
displayedLocationCode,
LOCATIONS[displayedLocationCode] || "Unknown",
);
}, [
addSearch,
displayedLocationCode,
queryKeyString,
request,
researchQuery.data,
researchQuery.isSuccess,
]);
const hasSearched = request !== null;
const hasSearched = parseKeywordInput(keywordInput).length > 0;
const rows = hasSearched ? (researchQuery.data?.rows ?? []) : [];
const researchError =
hasSearched && researchQuery.isError
@ -178,7 +179,7 @@ export function useKeywordResearchData(
researchQuery.data?.source ?? ("related" as ResearchSource),
lastUsedFallback: researchQuery.data?.usedFallback ?? false,
lastSearchKeyword: request?.seedKeyword ?? "",
lastSearchLocationCode: request?.locationCode ?? DEFAULT_LOCATION_CODE,
lastSearchLocationCode: displayedLocationCode,
researchError,
researchMutationError: researchQuery.error,
searchedKeyword: request?.seedKeyword ?? "",

6
src/client/features/keywords/hooks/useKeywordSerpAnalysis.ts
View File

@ -1,12 +1,11 @@
import { useQuery } from "@tanstack/react-query";
import { useState } from "react";
import { getStandardErrorMessage } from "@/client/lib/error-messages";
import { getLanguageCode } from "@/client/features/keywords/utils";
import { getSerpAnalysis } from "@/serverFunctions/keywords";
export function useKeywordSerpAnalysis(
projectId: string,
locationCode: number,
locationCode: number | undefined,
) {
const [serpKeyword, setSerpKeyword] = useState<string | null>(null);
const [serpPage, setSerpPage] = useState(0);
@ -20,7 +19,6 @@ export function useKeywordSerpAnalysis(
projectId,
keyword: serpKeyword!,
locationCode,
languageCode: getLanguageCode(locationCode),
},
}),
enabled: !!serpKeyword,
@ -29,7 +27,7 @@ export function useKeywordSerpAnalysis(
const serpResults = serpQuery.data?.items ?? [];
const activeSerpKeyword =
serpKeyword ?? serpQuery.data?.requestedKeyword ?? null;
const serpLoading = serpQuery.isLoading;
const serpLoading = !!serpKeyword && serpQuery.isLoading;
const serpError = serpQuery.isError
? getStandardErrorMessage(serpQuery.error, "Failed to load SERP data.")
: null;

55
src/client/features/keywords/hooks/usePreferredKeywordLocation.ts
View File

@ -5,12 +5,15 @@ import {
isSupportedLocationCode,
} from "@/client/features/keywords/locations";
const STORAGE_KEY = "keyword-preferred-location";
// Scoped per project: a location picked while working on one project must not
// shadow another project's own default market.
const storageKey = (projectId: string) =>
`keyword-preferred-location:${projectId}`;
const locationCodeSchema = z.number().int().positive();
function loadPreferredLocationCode() {
function loadPreferredLocationCode(projectId: string) {
try {
const raw = localStorage.getItem(STORAGE_KEY);
const raw = localStorage.getItem(storageKey(projectId));
if (!raw) return null;
const parsed = locationCodeSchema.parse(JSON.parse(raw));
@ -20,31 +23,49 @@ function loadPreferredLocationCode() {
}
}
function savePreferredLocationCode(locationCode: number) {
function savePreferredLocationCode(projectId: string, locationCode: number) {
try {
localStorage.setItem(STORAGE_KEY, JSON.stringify(locationCode));
localStorage.setItem(storageKey(projectId), JSON.stringify(locationCode));
} catch {
// storage full or unavailable - silently ignore
}
}
export function usePreferredKeywordLocation() {
const [preferredLocationCode, setPreferredLocationCodeState] = useState(
DEFAULT_LOCATION_CODE,
);
/**
* Preference order: the user's explicit choice for this project (persisted per
* browser) > the project's default market (may arrive async from the projects
* query) > the US fallback.
*/
export function usePreferredKeywordLocation(
projectId: string,
projectDefaultLocationCode?: number,
) {
const [preference, setPreference] = useState(() => ({
projectId,
locationCode: loadPreferredLocationCode(projectId),
}));
const chosenLocationCode =
preference.projectId === projectId
? preference.locationCode
: loadPreferredLocationCode(projectId);
useEffect(() => {
const savedLocationCode = loadPreferredLocationCode();
if (savedLocationCode != null) {
setPreferredLocationCodeState(savedLocationCode);
}
}, []);
if (preference.projectId === projectId) return;
setPreference({ projectId, locationCode: chosenLocationCode });
}, [chosenLocationCode, preference.projectId, projectId]);
const preferredLocationCode =
chosenLocationCode ?? projectDefaultLocationCode ?? DEFAULT_LOCATION_CODE;
function setPreferredLocationCode(locationCode: number) {
if (!isSupportedLocationCode(locationCode)) return;
setPreferredLocationCodeState(locationCode);
savePreferredLocationCode(locationCode);
setPreference({ projectId, locationCode });
savePreferredLocationCode(projectId, locationCode);
}
return { preferredLocationCode, setPreferredLocationCode };
return {
preferredLocationCode,
selectedLocationCode: chosenLocationCode ?? undefined,
setPreferredLocationCode,
};
}

6
src/client/features/keywords/page/KeywordResearchEmptyState.tsx
View File

@ -1,6 +1,5 @@
import { Link } from "@tanstack/react-router";
import { Clock, Globe, History, Search, X } from "lucide-react";
import { DEFAULT_LOCATION_CODE } from "@/client/features/keywords/locations";
import { LOCATIONS } from "@/client/features/keywords/utils";
import type { KeywordResearchControllerState } from "./types";
@ -89,10 +88,7 @@ function SearchHistoryState({
params={{ projectId }}
search={{
q: item.keyword,
loc:
item.locationCode === DEFAULT_LOCATION_CODE
? undefined
: item.locationCode,
loc: item.locationCode,
}}
replace
className="flex min-w-0 flex-1 items-center gap-3 rounded-md px-1 py-1 text-left transition-colors hover:bg-base-200"

58
src/client/features/keywords/page/KeywordResearchPage.tsx
View File

@ -7,21 +7,30 @@ import { useKeywordResearchController } from "@/client/features/keywords/state/u
import type { KeywordResearchControllerInput } from "@/client/features/keywords/state/useKeywordResearchController";
import type { KeywordControlsValues } from "@/client/features/keywords/hooks/useKeywordControlsForm";
import { parseKeywordInput } from "@/client/features/keywords/state/keywordControllerActions";
import { useKeywordSearchParams } from "@/client/features/keywords/state/keywordControllerInternals";
import { DEFAULT_LOCATION_CODE } from "@/client/features/keywords/locations";
import {
useKeywordSearchParams,
useResolvedKeywordLocation,
} from "@/client/features/keywords/state/keywordControllerInternals";
import type {
KeywordSearchTabInput,
SearchTab,
} from "@/client/features/search-tabs/types";
import { SearchTabStrip } from "@/client/features/search-tabs/SearchTabStrip";
import { useSearchTabNavigation } from "@/client/features/search-tabs/useSearchTabNavigation";
import {
tabInputKey,
useSearchTabNavigation,
} from "@/client/features/search-tabs/useSearchTabNavigation";
import { KeywordResearchEmptyState } from "./KeywordResearchEmptyState";
import { KeywordResearchLoadingState } from "./KeywordResearchLoadingState";
import { KeywordResearchResults } from "./KeywordResearchResults";
import { KeywordResearchSearchBar } from "./KeywordResearchSearchBar";
import type { KeywordResearchControllerState } from "./types";
type Props = Omit<KeywordResearchControllerInput, "onFormSubmit">;
type ControllerProps = Omit<KeywordResearchControllerInput, "onFormSubmit">;
type Props = Omit<
ControllerProps,
"locationCode" | "displayedLocationCode" | "setPreferredLocationCode"
> & { locationCode?: number };
type KeywordSearchTab = SearchTab & { input: KeywordSearchTabInput };
function isKeywordSearchTab(tab: SearchTab): tab is KeywordSearchTab {
@ -31,6 +40,11 @@ function isKeywordSearchTab(tab: SearchTab): tab is KeywordSearchTab {
export function KeywordResearchPage(input: Props) {
const setSearchParams = useKeywordSearchParams();
const projectId = input.projectId;
const { locationCode, displayedLocationCode, setPreferredLocationCode } =
useResolvedKeywordLocation({
projectId,
locationCode: input.locationCode,
});
const navigateToKeywordInput = useCallback(
(tabInput: KeywordSearchTabInput | null) => {
@ -47,10 +61,7 @@ export function KeywordResearchPage(input: Props) {
setSearchParams({
q: tabInput.keyword,
loc:
tabInput.locationCode === DEFAULT_LOCATION_CODE
? undefined
: tabInput.locationCode,
loc: tabInput.locationCode,
kLimit: tabInput.resultLimit === 150 ? undefined : tabInput.resultLimit,
mode: tabInput.mode === "auto" ? undefined : tabInput.mode,
cs: tabInput.clickstream ? true : undefined,
@ -66,7 +77,7 @@ export function KeywordResearchPage(input: Props) {
return {
type: "keyword",
keyword,
locationCode: input.locationCode,
locationCode,
resultLimit: input.resultLimit,
mode: input.keywordMode,
clickstream: input.clickstream,
@ -75,7 +86,7 @@ export function KeywordResearchPage(input: Props) {
input.clickstream,
input.keywordInput,
input.keywordMode,
input.locationCode,
locationCode,
input.resultLimit,
]);
const searchTabs = useSearchTabNavigation({
@ -98,7 +109,13 @@ export function KeywordResearchPage(input: Props) {
const tab = searchTabs.tabs.find(
(candidate) => candidate.id === searchTabs.activeTabId,
);
return tab && isKeywordSearchTab(tab) ? tab : null;
// activeTabId syncs in an effect, so it trails urlInput by a render; the
// stale tab must not drive a paid query for a market the URL no longer names.
return tab &&
isKeywordSearchTab(tab) &&
tabInputKey(tab.input) === tabInputKey(urlInput)
? tab
: null;
}, [searchTabs.activeTabId, searchTabs.tabs, urlInput]);
const onFormSubmit = useCallback(
@ -148,14 +165,16 @@ export function KeywordResearchPage(input: Props) {
[searchTabs.tabs],
);
const controllerInput = useMemo<Props>(
const controllerInput = useMemo<ControllerProps>(
() =>
activeTab
? {
...input,
keywordInput: activeTab.input.keyword,
locationCode: activeTab.input.locationCode,
hasExplicitLocationCode: true,
displayedLocationCode:
activeTab.input.locationCode ?? displayedLocationCode,
setPreferredLocationCode,
resultLimit: activeTab.input.resultLimit,
keywordMode: activeTab.input.mode,
clickstream: activeTab.input.clickstream,
@ -164,10 +183,21 @@ export function KeywordResearchPage(input: Props) {
}
: {
...input,
locationCode,
displayedLocationCode,
setPreferredLocationCode,
getOpenKeywordTabs,
keywordTabsLimit: searchTabs.limit,
},
[activeTab, getOpenKeywordTabs, input, searchTabs.limit],
[
activeTab,
getOpenKeywordTabs,
input,
displayedLocationCode,
locationCode,
searchTabs.limit,
setPreferredLocationCode,
],
);
const controller = useKeywordResearchController({
...controllerInput,

4
src/client/features/keywords/state/keywordControllerActions.ts
View File

@ -3,7 +3,6 @@ import { toast } from "sonner";
import { buildCsv, type CsvValue, downloadCsv } from "@/client/lib/csv";
import { getStandardErrorMessage } from "@/client/lib/error-messages";
import { captureClientEvent } from "@/client/lib/posthog";
import { getLanguageCode } from "@/client/features/keywords/utils";
import type { KeywordResearchRow } from "@/types/keywords";
import type { SaveKeywordsInput } from "@/types/schemas/keywords";
import type { SortDir, SortField } from "@/client/features/keywords/components";
@ -62,7 +61,7 @@ export function parseKeywordInput(value: string) {
*/
export function buildKeywordSearchKey(params: {
keyword: string;
locationCode: number;
locationCode: number | undefined;
resultLimit: ResultLimit;
mode: KeywordMode;
clickstream: boolean;
@ -127,7 +126,6 @@ export function useSaveAndExportActions(params: SaveExportActionParams) {
projectId: input.projectId,
keywords: [...selectedRows],
locationCode: input.locationCode,
languageCode: getLanguageCode(input.locationCode),
metrics,
},
{

25
src/client/features/keywords/state/keywordControllerInternals.ts
View File

@ -2,22 +2,25 @@ import { useNavigate } from "@tanstack/react-router";
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { useCallback, useState } from "react";
import { usePreferredKeywordLocation } from "@/client/features/keywords/hooks/usePreferredKeywordLocation";
import { useProjectMarket } from "@/client/features/projects/useProjectMarket";
import { saveKeywords } from "@/serverFunctions/keywords";
import type { SaveKeywordsInput } from "@/types/schemas/keywords";
import type { KeywordResearchRow } from "@/types/keywords";
import type { KeywordResearchControllerInput } from "./useKeywordResearchController";
export function useResolvedKeywordLocation(
input: KeywordResearchControllerInput,
) {
const { preferredLocationCode, setPreferredLocationCode } =
usePreferredKeywordLocation();
const locationCode =
!input.hasExplicitLocationCode && input.keywordInput === ""
? preferredLocationCode
: input.locationCode;
export function useResolvedKeywordLocation(input: {
projectId: string;
locationCode?: number;
}) {
const projectMarket = useProjectMarket(input.projectId);
const {
preferredLocationCode,
selectedLocationCode,
setPreferredLocationCode,
} = usePreferredKeywordLocation(input.projectId, projectMarket?.locationCode);
const locationCode = input.locationCode ?? selectedLocationCode;
const displayedLocationCode = input.locationCode ?? preferredLocationCode;
return { locationCode, setPreferredLocationCode };
return { locationCode, displayedLocationCode, setPreferredLocationCode };
}
export function useKeywordUiState(initialShowFilters: boolean) {

15
src/client/features/keywords/state/useKeywordResearchController.ts
View File

@ -25,13 +25,12 @@ import {
useKeywordSaveMutation,
useKeywordSearchParams,
useKeywordUiState,
useResolvedKeywordLocation,
} from "./keywordControllerInternals";
import { useKeywordOverviewState } from "./useKeywordOverviewState";
type OpenKeywordTabInput = {
keyword: string;
locationCode: number;
locationCode: number | undefined;
resultLimit: ResultLimit;
mode: KeywordMode;
clickstream: boolean;
@ -40,8 +39,9 @@ type OpenKeywordTabInput = {
export type KeywordResearchControllerInput = {
projectId: string;
keywordInput: string;
locationCode: number;
hasExplicitLocationCode: boolean;
locationCode: number | undefined;
displayedLocationCode: number;
setPreferredLocationCode: (locationCode: number) => void;
resultLimit: ResultLimit;
keywordMode: KeywordMode;
clickstream: boolean;
@ -60,8 +60,8 @@ export type KeywordResearchControllerInput = {
export function useKeywordResearchController(
input: KeywordResearchControllerInput,
) {
const { locationCode, setPreferredLocationCode } =
useResolvedKeywordLocation(input);
const { displayedLocationCode, locationCode, setPreferredLocationCode } =
input;
const {
filtersForm,
values: filterValues,
@ -115,6 +115,7 @@ export function useKeywordResearchController(
projectId: input.projectId,
keywordInput: input.keywordInput,
locationCode,
displayedLocationCode,
resultLimit: input.resultLimit,
mode: input.keywordMode,
clickstream: input.clickstream,
@ -148,7 +149,7 @@ export function useKeywordResearchController(
const controlsForm = useKeywordControlsForm(
{
...input,
locationCode,
locationCode: displayedLocationCode,
getOpenKeywordTabs: input.getOpenKeywordTabs,
keywordTabsLimit: input.keywordTabsLimit,
},

2
src/client/features/keywords/utils.ts
View File

@ -1,4 +1,4 @@
export { LOCATIONS, getLanguageCode } from "./locations";
export { LOCATIONS } from "./locations";
export function scoreTierClass(value: number | null): string {
if (value == null) return "score-tier-na";

67
src/client/features/onboarding/SearchConsoleOnboardingStep.tsx
View File

@ -11,12 +11,14 @@ import {
import { startGscLink } from "@/client/features/gsc/startGscLink";
import { getStandardErrorMessage } from "@/client/lib/error-messages";
import { captureClientEvent } from "@/client/lib/posthog";
import { ProjectMarketFields } from "@/client/features/projects/ProjectMarketFields";
import type { ProjectMarket } from "@/client/features/projects/types";
import {
getGscConnection,
listGscSites,
setGscSite,
} from "@/serverFunctions/gsc";
import { getProjects } from "@/serverFunctions/projects";
import { getProjects, setProjectMarket } from "@/serverFunctions/projects";
const GRANT_STATUS_KEY = ["gscGrantStatus"];
@ -31,19 +33,66 @@ export function SearchConsoleOnboardingStep() {
queryKey: ["projects"],
queryFn: () => getProjects(),
});
const projectId = projectsQuery.data?.[0]?.id;
const project = projectsQuery.data?.[0];
return (
<div className="space-y-4">
<h2 className="text-lg font-semibold">
Connect with Google Search Console now?
</h2>
<div className="space-y-8">
<div className="space-y-4">
<h2 className="text-lg font-semibold">
Connect with Google Search Console now?
</h2>
{projectId ? <GscConnect projectId={projectId} /> : <Checking />}
{project ? <GscConnect projectId={project.id} /> : <Checking />}
<p className="text-xs leading-relaxed text-base-content/55">
For now, Search Console data flows through the OpenSEO MCP. We're
building it into the OpenSEO app soon too.
</p>
</div>
<div className="space-y-4">
<h2 className="text-lg font-semibold">Choose country &amp; language</h2>
{project ? <DefaultMarketPicker project={project} /> : <Checking />}
</div>
</div>
);
}
/**
* Sets the project's default market during onboarding, so keyword, SERP, and
* domain data lands on the user's market from their first search instead of
* defaulting to the US. Saves on change — the step's Continue button belongs
* to the wizard, so a separate Save here would be easy to walk past.
*/
function DefaultMarketPicker({
project,
}: {
project: { id: string; locationCode: number; languageCode: string };
}) {
const queryClient = useQueryClient();
const [market, setMarket] = React.useState<ProjectMarket>({
locationCode: project.locationCode,
languageCode: project.languageCode,
});
const saveMutation = useMutation({
mutationFn: (next: ProjectMarket) =>
setProjectMarket({ data: { projectId: project.id, ...next } }),
onSuccess: () => queryClient.invalidateQueries({ queryKey: ["projects"] }),
onError: (error) => toast.error(getStandardErrorMessage(error)),
});
const handleChange = (next: ProjectMarket) => {
setMarket(next);
saveMutation.mutate(next);
};
return (
<div className="space-y-2">
<ProjectMarketFields value={market} onChange={handleChange} />
<p className="text-xs leading-relaxed text-base-content/55">
For now, Search Console data flows through the OpenSEO MCP. We're
building it into the OpenSEO app soon too.
We'll use this country and language for keyword, SERP, and domain data
unless you pick a different one. You can change it in project settings.
</p>
</div>
);

24
src/client/features/projects/CreateProjectModal.tsx
View File

@ -5,6 +5,11 @@ import { toast } from "sonner";
import { Modal } from "@/client/components/Modal";
import { getStandardErrorMessage } from "@/client/lib/error-messages";
import { setLastProjectId } from "@/client/lib/active-project";
import {
DEFAULT_LOCATION_CODE,
getLanguageCode,
} from "@/client/features/keywords/locations";
import { ProjectMarketFields } from "@/client/features/projects/ProjectMarketFields";
import { createProject } from "@/serverFunctions/projects";
export function CreateProjectModal({ onClose }: { onClose: () => void }) {
@ -12,11 +17,19 @@ export function CreateProjectModal({ onClose }: { onClose: () => void }) {
const queryClient = useQueryClient();
const [name, setName] = React.useState("");
const [domain, setDomain] = React.useState("");
const [market, setMarket] = React.useState({
locationCode: DEFAULT_LOCATION_CODE,
languageCode: getLanguageCode(DEFAULT_LOCATION_CODE),
});
const createMutation = useMutation({
mutationFn: () =>
createProject({
data: { name: name.trim(), domain: domain.trim() || undefined },
data: {
name: name.trim(),
domain: domain.trim() || undefined,
...market,
},
}),
onSuccess: async (created) => {
setLastProjectId(created.id);
@ -88,6 +101,15 @@ export function CreateProjectModal({ onClose }: { onClose: () => void }) {
</span>
</label>
<div className="flex flex-col gap-1.5">
<ProjectMarketFields value={market} onChange={setMarket} />
<span className="text-xs text-base-content/50">
Keyword, SERP, and domain data uses this country and language unless
a call asks for a different one. Change it later in project
settings.
</span>
</div>
<div className="flex justify-end gap-2">
<button
type="button"

58
src/client/features/projects/ProjectMarketFields.tsx Normal file
View File

@ -0,0 +1,58 @@
import { LocationSelect } from "@/client/components/LocationSelect";
import {
getLanguageCode,
getLanguageOptions,
} from "@/client/features/keywords/locations";
import type { ProjectMarket } from "@/client/features/projects/types";
/**
* The project's default market: country plus the language served for it.
* Shared by project settings and onboarding so the pair — and the rule that
* changing the country snaps the language to that country's native one —
* stays identical in both places.
*/
export function ProjectMarketFields({
value,
onChange,
}: {
value: ProjectMarket;
onChange: (market: ProjectMarket) => void;
}) {
const languageOptions = getLanguageOptions(value.locationCode);
return (
<div className="grid gap-4 sm:grid-cols-2">
<label className="flex flex-col gap-1.5 text-sm">
<span className="font-medium">Country</span>
<LocationSelect
value={value.locationCode}
onChange={(locationCode) =>
onChange({
locationCode,
languageCode: getLanguageCode(locationCode),
})
}
/>
</label>
<label className="flex flex-col gap-1.5 text-sm">
<span className="font-medium">Language</span>
<select
value={value.languageCode}
onChange={(event) =>
onChange({ ...value, languageCode: event.target.value })
}
// Most countries have exactly one language DataForSEO serves, so the
// select is only a real choice where there's more than one.
disabled={languageOptions.length <= 1}
className="select select-bordered w-full"
>
{languageOptions.map((option) => (
<option key={option.code} value={option.code}>
{option.label}
</option>
))}
</select>
</label>
</div>
);
}

18
src/client/features/projects/ProjectSettings.tsx
View File

@ -4,6 +4,7 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { ChevronLeft } from "lucide-react";
import { toast } from "sonner";
import { SearchConsoleConnectionCard } from "@/client/features/gsc/SearchConsoleConnectionCard";
import { ProjectMarketFields } from "@/client/features/projects/ProjectMarketFields";
import { getStandardErrorMessage } from "@/client/lib/error-messages";
import {
clearLastProjectId,
@ -69,6 +70,10 @@ function GeneralSection({ project }: { project: ProjectSummary }) {
const queryClient = useQueryClient();
const [name, setName] = React.useState(project.name);
const [domain, setDomain] = React.useState(project.domain ?? "");
const [market, setMarket] = React.useState({
locationCode: project.locationCode,
languageCode: project.languageCode,
});
const updateMutation = useMutation({
mutationFn: () =>
@ -77,6 +82,7 @@ function GeneralSection({ project }: { project: ProjectSummary }) {
projectId: project.id,
name: name.trim(),
domain: domain.trim() || undefined,
...market,
},
}),
onSuccess: async () => {
@ -89,7 +95,9 @@ function GeneralSection({ project }: { project: ProjectSummary }) {
const isDirty =
name.trim() !== project.name ||
(domain.trim() || "") !== (project.domain ?? "");
(domain.trim() || "") !== (project.domain ?? "") ||
market.locationCode !== project.locationCode ||
market.languageCode !== project.languageCode;
const handleSubmit = (event: React.FormEvent) => {
event.preventDefault();
@ -130,6 +138,14 @@ function GeneralSection({ project }: { project: ProjectSummary }) {
/>
</label>
<div className="flex flex-col gap-1.5">
<ProjectMarketFields value={market} onChange={setMarket} />
<span className="text-xs text-base-content/50">
Keyword, SERP, and domain data uses this country and language unless
a call asks for a different one.
</span>
</div>
<div className="flex justify-end">
<button
type="submit"

7
src/client/features/projects/types.ts
View File

@ -1,7 +1,14 @@
// The project's default market: the country/language pair its data calls
// fall back to. Mirrors resolveMarket's project argument in shared/.
export type ProjectMarket = { locationCode: number; languageCode: string };
// Shape returned by the getProjects server function (a mapped project row).
export type ProjectSummary = {
id: string;
name: string;
domain: string | null;
// Default market for the project's data calls.
locationCode: number;
languageCode: string;
createdAt: string;
};

13
src/client/features/projects/useProjectMarket.ts Normal file
View File

@ -0,0 +1,13 @@
import { useQuery } from "@tanstack/react-query";
import { getProjects } from "@/serverFunctions/projects";
import type { ProjectMarket } from "./types";
/** The project's default market, or undefined until the projects query resolves. */
export function useProjectMarket(projectId: string): ProjectMarket | undefined {
const projectsQuery = useQuery({
queryKey: ["projects"],
queryFn: () => getProjects(),
});
return projectsQuery.data?.find((project) => project.id === projectId);
}

11
src/client/features/rank-tracking/KeywordSuggestionStep.tsx
View File

@ -140,7 +140,6 @@ export function KeywordSuggestionStep({
projectId,
domain,
locationCode,
languageCode,
onDone,
onClose,
}: Props) {
@ -163,16 +162,10 @@ export function KeywordSuggestionStep({
// Ads keyword data (e.g. Iceland) have no ranking data to suggest from.
const labsSupported = isLabsLocationCode(locationCode);
const suggestionsQuery = useQuery({
queryKey: [
"domainKeywordSuggestions",
projectId,
domain,
locationCode,
languageCode,
],
queryKey: ["domainKeywordSuggestions", projectId, domain, locationCode],
queryFn: () =>
getDomainKeywordSuggestions({
data: { projectId, domain, locationCode, languageCode },
data: { projectId, domain, locationCode },
}),
enabled: labsSupported,
});

47
src/client/features/rank-tracking/RankTrackingConfigModal.tsx
View File

@ -10,12 +10,13 @@ import {
estimateRankCheckCredits,
} from "@/shared/rank-tracking";
import {
DEFAULT_LOCATION_CODE,
getLanguageCode,
getLanguageOptions,
} from "@/client/features/keywords/locations";
import { getIsoCountryCode } from "@/shared/keyword-locations";
import { LocationSelect } from "@/client/components/LocationSelect";
import type { ProjectMarket } from "@/client/features/projects/types";
import { useProjectMarket } from "@/client/features/projects/useProjectMarket";
import { SearchTargetingField } from "./SearchTargetingField";
import { KeywordSuggestionStep } from "./KeywordSuggestionStep";
import { useSaveConfigMutations } from "./useSaveConfigMutations";
@ -35,6 +36,45 @@ export function RankTrackingConfigModal({
onSaved,
onConfigCreated,
}: Props) {
const projectMarket = useProjectMarket(projectId);
if (!existingConfig && !projectMarket) {
return (
<Modal
maxWidth="max-w-lg"
onClose={onClose}
labelledBy="rank-config-modal-title"
>
<h2 id="rank-config-modal-title" className="sr-only">
Add Domain
</h2>
<div className="flex min-h-40 items-center justify-center">
<Loader2 className="size-5 animate-spin text-base-content/50" />
</div>
</Modal>
);
}
return (
<RankTrackingConfigModalContent
projectId={projectId}
existingConfig={existingConfig}
initialMarket={existingConfig ?? projectMarket!}
onClose={onClose}
onSaved={onSaved}
onConfigCreated={onConfigCreated}
/>
);
}
function RankTrackingConfigModalContent({
projectId,
existingConfig,
initialMarket,
onClose,
onSaved,
onConfigCreated,
}: Props & { initialMarket: ProjectMarket }) {
const isEdit = !!existingConfig;
const [step, setStep] = useState<"config" | "keywords">("config");
const [domain, setDomain] = useState(existingConfig?.domain ?? "");
@ -42,11 +82,10 @@ export function RankTrackingConfigModal({
existingConfig?.devices ?? "mobile",
);
const [locationCode, setLocationCode] = useState(
existingConfig?.locationCode ?? DEFAULT_LOCATION_CODE,
existingConfig?.locationCode ?? initialMarket.locationCode,
);
const [languageCode, setLanguageCode] = useState(
existingConfig?.languageCode ??
getLanguageCode(existingConfig?.locationCode ?? DEFAULT_LOCATION_CODE),
existingConfig?.languageCode ?? initialMarket.languageCode,
);
const languageOptions = useMemo(
() => getLanguageOptions(locationCode),

4
src/client/features/search-tabs/SearchTabStrip.tsx
View File

@ -9,7 +9,6 @@ import {
buildKeywordResearchRequest,
keywordResearchQueryFn,
} from "@/client/features/keywords/hooks/useKeywordResearchData";
import { getLanguageCode } from "@/client/features/keywords/locations";
import { getBacklinksOverview } from "@/serverFunctions/backlinks";
import { getDomainOverview } from "@/serverFunctions/domain";
export type { SearchTab } from "./types";
@ -187,7 +186,6 @@ function getSearchTabQueryConfig(
if (tab.input.type === "domain") {
const input = tab.input;
const trimmedDomain = input.domain.trim();
const languageCode = getLanguageCode(input.locationCode);
return {
queryKey: [
@ -196,7 +194,6 @@ function getSearchTabQueryConfig(
trimmedDomain,
input.subdomains,
input.locationCode,
languageCode,
],
queryFn: () =>
getDomainOverview({
@ -205,7 +202,6 @@ function getSearchTabQueryConfig(
domain: trimmedDomain,
includeSubdomains: input.subdomains,
locationCode: input.locationCode,
languageCode,
},
}),
staleTime: 5 * 60_000,

4
src/client/features/search-tabs/types.ts
View File

@ -14,13 +14,13 @@ export type DomainSearchTabInput = {
type: "domain";
domain: string;
subdomains: boolean;
locationCode: number;
locationCode?: number;
};
export type KeywordSearchTabInput = {
type: "keyword";
keyword: string;
locationCode: number;
locationCode?: number;
resultLimit: ResultLimit;
mode: KeywordMode;
clickstream: boolean;

2
src/client/features/search-tabs/useSearchTabNavigation.ts
View File

@ -9,7 +9,7 @@ type UseSearchTabNavigationArgs = {
navigateToInput: (input: SearchTabInput | null) => void;
};
function tabInputKey(input: SearchTabInput | null) {
export function tabInputKey(input: SearchTabInput | null) {
return input ? JSON.stringify(input) : "";
}

6
src/routes/_project/p/$projectId/domain.tsx
View File

@ -8,8 +8,8 @@ import {
DEFAULT_DOMAIN_KEYWORDS_PAGE_SIZE,
domainSearchSchema,
} from "@/types/schemas/domain";
import { DEFAULT_LOCATION_CODE } from "@/client/features/keywords/locations";
import { getDomainRouteState } from "@/client/features/domain/domainRouteState";
import { useProjectMarket } from "@/client/features/projects/useProjectMarket";
const DEFAULT_DOMAIN_SEARCH = {
domain: "",
@ -17,7 +17,6 @@ const DEFAULT_DOMAIN_SEARCH = {
sort: "traffic",
order: undefined,
tab: "keywords",
loc: DEFAULT_LOCATION_CODE,
page: 1,
size: DEFAULT_DOMAIN_KEYWORDS_PAGE_SIZE,
include: "",
@ -52,7 +51,8 @@ function DomainOverviewRoute() {
const { projectId } = Route.useParams();
const navigate = useNavigate({ from: Route.fullPath });
const search = Route.useSearch();
const routeState = getDomainRouteState(search);
const projectMarket = useProjectMarket(projectId);
const routeState = getDomainRouteState(search, projectMarket);
return (
<DomainOverviewPage

6
src/routes/_project/p/$projectId/keywords.tsx
View File

@ -1,5 +1,4 @@
import { createFileRoute, redirect } from "@tanstack/react-router";
import { DEFAULT_LOCATION_CODE } from "@/client/features/keywords/locations";
import { KeywordResearchPage } from "@/client/features/keywords/page/KeywordResearchPage";
import {
isResultLimit,
@ -31,20 +30,17 @@ function KeywordResearchPageRoute() {
const search = Route.useSearch();
const {
q: keywordInput = "",
loc: rawLocationCode,
loc: locationCode,
kLimit: resultLimit = 150,
mode: keywordMode = "auto",
sort: sortField = "searchVolume",
order: sortDir = "desc",
} = search;
const locationCode = rawLocationCode ?? DEFAULT_LOCATION_CODE;
return (
<KeywordResearchPage
projectId={projectId}
keywordInput={keywordInput}
locationCode={locationCode}
hasExplicitLocationCode={search.loc != null}
resultLimit={isResultLimit(resultLimit) ? resultLimit : 150}
keywordMode={normalizeKeywordMode(keywordMode)}
clickstream={search.cs ?? false}

21
src/server/features/keywords/services/research/research.ts
View File

@ -9,7 +9,7 @@ import {
} from "@/server/lib/r2-cache";
import { KeywordResearchRepository } from "@/server/features/keywords/repositories/KeywordResearchRepository";
import type { KeywordResearchRow } from "@/types/keywords";
import type { ResearchKeywordsInput } from "@/types/schemas/keywords";
import type { ResolvedResearchKeywordsInput } from "@/types/schemas/keywords";
import { z } from "zod";
import { getKeywordDataProvider } from "@/shared/keyword-locations";
import { type EnrichedKeyword, normalizeKeyword } from "./helpers";
@ -93,7 +93,7 @@ const CACHE_VERSION = 3;
async function fetchRowsFromSource(
source: KeywordSource,
input: ResearchKeywordsInput,
input: ResolvedResearchKeywordsInput,
seedKeyword: string,
billingCustomer: BillingCustomerContext,
creditFeature?: CreditFeature,
@ -113,7 +113,7 @@ async function fetchRowsFromSource(
}
async function fetchAutoRows(
input: ResearchKeywordsInput,
input: ResolvedResearchKeywordsInput,
seedKeyword: string,
billingCustomer: BillingCustomerContext,
creditFeature?: CreditFeature,
@ -175,7 +175,7 @@ async function fetchAutoRows(
}
async function fetchGoogleAdsRows(
input: ResearchKeywordsInput,
input: ResolvedResearchKeywordsInput,
seedKeyword: string,
billingCustomer: BillingCustomerContext,
creditFeature?: CreditFeature,
@ -211,7 +211,7 @@ async function fetchGoogleAdsRows(
async function fetchManualRows(
mode: Exclude<KeywordMode, "auto">,
input: ResearchKeywordsInput,
input: ResolvedResearchKeywordsInput,
seedKeyword: string,
billingCustomer: BillingCustomerContext,
creditFeature?: CreditFeature,
@ -242,7 +242,7 @@ async function fetchManualRows(
}
async function buildResearchCacheKey(
input: ResearchKeywordsInput,
input: ResolvedResearchKeywordsInput,
normalizedKeywords: string[],
mode: KeywordMode,
billingCustomer: BillingCustomerContext,
@ -261,7 +261,10 @@ async function buildResearchCacheKey(
});
}
function persistRows(input: ResearchKeywordsInput, rows: EnrichedKeyword[]) {
function persistRows(
input: ResolvedResearchKeywordsInput,
rows: EnrichedKeyword[],
) {
void Promise.all(
rows.map((row) =>
KeywordResearchRepository.upsertKeywordMetric({
@ -283,7 +286,7 @@ function persistRows(input: ResearchKeywordsInput, rows: EnrichedKeyword[]) {
}
export async function research(
input: ResearchKeywordsInput,
input: ResolvedResearchKeywordsInput,
billingCustomer: BillingCustomerContext,
creditFeature?: CreditFeature,
): Promise<ResearchResult> {
@ -300,7 +303,7 @@ export async function research(
// Labs source modes and clickstream refinement don't exist for
// Google-Ads-served countries; collapse both so equivalent requests share
// one cache entry.
const effectiveInput: ResearchKeywordsInput =
const effectiveInput: ResolvedResearchKeywordsInput =
provider === "google_ads"
? { ...input, mode: "auto", clickstream: false }
: input;

4
src/server/features/keywords/services/research/saved-keywords.ts
View File

@ -5,7 +5,7 @@ import type {
ExportSavedKeywordsInput,
GetSavedKeywordsInput,
RemoveSavedKeywordsInput,
SaveKeywordsInput,
ResolvedSaveKeywordsInput,
UpdateSavedKeywordTagInput,
UpdateSavedKeywordTagsInput,
} from "@/types/schemas/keywords";
@ -31,7 +31,7 @@ function parseMonthlySearches(payload: string | null): MonthlySearch[] {
return result.success ? result.data : [];
}
export async function saveKeywords(input: SaveKeywordsInput) {
export async function saveKeywords(input: ResolvedSaveKeywordsInput) {
const normalizedKeywords = [
...new Set(
input.keywords.map(normalizeKeyword).filter((kw) => kw.length > 0),

42
src/server/features/projects/repositories/ProjectRepository.ts
View File

@ -61,11 +61,13 @@ async function createProject(
organizationId: string,
name: string,
domain?: string,
// Omitted keeps the column defaults.
market?: { locationCode: number; languageCode: string },
) {
const id = crypto.randomUUID();
const [row] = await db
.insert(projects)
.values({ id, organizationId, name, domain })
.values({ id, organizationId, name, domain, ...market })
.returning();
return row;
}
@ -73,15 +75,48 @@ async function createProject(
async function updateProject(
projectId: string,
organizationId: string,
input: { name: string; domain?: string },
input: {
name: string;
domain?: string;
// Omitted leaves the market columns untouched.
market?: { locationCode: number; languageCode: string };
},
) {
const [row] = await db
.update(projects)
.set({ name: input.name, domain: input.domain ?? null })
.set({ name: input.name, domain: input.domain ?? null, ...input.market })
.where(
and(
eq(projects.id, projectId),
eq(projects.organizationId, organizationId),
isNull(projects.archivedAt),
),
)
.returning();
if (!row) {
throw new AppError("NOT_FOUND");
}
return row;
}
// Writes only the market columns. Onboarding sets the project's market before
// the user has named the project or picked a domain, so it must not go through
// updateProject, whose `domain: input.domain ?? null` would clear the domain.
async function updateProjectMarket(
projectId: string,
organizationId: string,
market: { locationCode: number; languageCode: string },
) {
const [row] = await db
.update(projects)
.set(market)
.where(
and(
eq(projects.id, projectId),
eq(projects.organizationId, organizationId),
isNull(projects.archivedAt),
),
)
.returning();
@ -162,6 +197,7 @@ export const ProjectRepository = {
getProjectById,
createProject,
updateProject,
updateProjectMarket,
tryCreateDefaultProject,
archiveProject,
restoreProject,

2
src/server/features/projects/services/ProjectService.ts
View File

@ -6,6 +6,7 @@ import {
listProjects,
listProjectsEnsuringOne,
restoreProject,
setProjectMarket,
updateProject,
} from "@/server/features/projects/services/projects";
@ -14,6 +15,7 @@ export const ProjectService = {
listProjectsEnsuringOne,
createProject,
updateProject,
setProjectMarket,
archiveProject,
restoreProject,
listArchivedProjects,

102
src/server/features/projects/services/projects.test.ts
View File

@ -6,6 +6,7 @@ const mocks = vi.hoisted(() => ({
archiveProject: vi.fn(),
restoreProject: vi.fn(),
countProjects: vi.fn(),
updateProjectMarket: vi.fn(),
getProjectForOrganization: vi.fn(),
listProjects: vi.fn(),
listArchivedProjects: vi.fn(),
@ -89,9 +90,40 @@ describe("project service", () => {
"org_1",
"Acme",
"acme.com",
undefined,
);
});
it("derives the native language when only the location is given", async () => {
mocks.createProject.mockResolvedValue(namedProject);
const { createProject } = await import("./projects");
await createProject("org_1", {
name: "Acme",
domain: "acme.com",
locationCode: 2704,
});
expect(mocks.createProject).toHaveBeenCalledWith(
"org_1",
"Acme",
"acme.com",
{ locationCode: 2704, languageCode: "vi" },
);
});
it("rejects a language DataForSEO does not serve for the location", async () => {
const { createProject } = await import("./projects");
await expect(
createProject("org_1", {
name: "Acme",
locationCode: 2840,
languageCode: "vi",
}),
).rejects.toMatchObject({ code: "VALIDATION_ERROR" });
expect(mocks.createProject).not.toHaveBeenCalled();
});
it("maps the reserved Default conflict to a friendly CONFLICT", async () => {
mocks.createProject.mockRejectedValue(
new Error(
@ -107,6 +139,37 @@ describe("project service", () => {
});
describe("updateProject", () => {
it("leaves the market columns untouched when neither half is given", async () => {
mocks.updateProject.mockResolvedValue(namedProject);
const { updateProject } = await import("./projects");
await updateProject("org_1", { projectId: "project_acme", name: "Acme" });
expect(mocks.updateProject).toHaveBeenCalledWith(
"project_acme",
"org_1",
expect.objectContaining({ market: undefined }),
);
});
it("snaps the language on a location-only change without reading the stored row", async () => {
mocks.updateProject.mockResolvedValue(namedProject);
const { updateProject } = await import("./projects");
await updateProject("org_1", {
projectId: "project_acme",
name: "Acme",
locationCode: 2276,
});
expect(mocks.getProjectForOrganization).not.toHaveBeenCalled();
expect(mocks.updateProject).toHaveBeenCalledWith(
"project_acme",
"org_1",
expect.objectContaining({
market: { locationCode: 2276, languageCode: "de" },
}),
);
});
it("returns the updated project", async () => {
mocks.updateProject.mockResolvedValue(namedProject);
const { updateProject } = await import("./projects");
@ -145,6 +208,45 @@ describe("project service", () => {
});
});
describe("setProjectMarket", () => {
it("writes only the market columns, leaving name and domain untouched", async () => {
// Onboarding sets the market before the project is named or given a
// domain; going through updateProject would clear the domain.
mocks.updateProjectMarket.mockResolvedValue({
...namedProject,
locationCode: 2704,
languageCode: "vi",
});
const { setProjectMarket } = await import("./projects");
await setProjectMarket("org_1", {
projectId: "project_acme",
locationCode: 2704,
languageCode: "vi",
});
expect(mocks.updateProjectMarket).toHaveBeenCalledWith(
"project_acme",
"org_1",
{ locationCode: 2704, languageCode: "vi" },
);
expect(mocks.updateProject).not.toHaveBeenCalled();
});
it("rejects a language the location does not serve before any write", async () => {
const { setProjectMarket } = await import("./projects");
await expect(
setProjectMarket("org_1", {
projectId: "project_acme",
locationCode: 2840,
languageCode: "vi",
}),
).rejects.toMatchObject({ code: "VALIDATION_ERROR" });
expect(mocks.updateProjectMarket).not.toHaveBeenCalled();
});
});
describe("archiveProject", () => {
it("refuses to archive the org's only project", async () => {
mocks.countProjects.mockResolvedValue(1);

50
src/server/features/projects/services/projects.ts
View File

@ -2,25 +2,50 @@ import type {
ArchiveProjectInput,
CreateProjectInput,
RestoreProjectInput,
SetProjectMarketInput,
UpdateProjectInput,
} from "@/types/schemas/projects";
import { ProjectRepository } from "@/server/features/projects/repositories/ProjectRepository";
import { AppError } from "@/server/lib/errors";
import { assertLanguageForLocation } from "@/server/lib/market";
import { getLanguageCode } from "@/shared/keyword-locations";
function mapProject(project: {
id: string;
name: string;
domain: string | null;
locationCode: number;
languageCode: string;
createdAt: string;
}) {
return {
id: project.id,
name: project.name,
domain: project.domain,
// Default market for the project's data calls (MCP tools and the web UI
// fall back to these when a call omits locationCode/languageCode).
locationCode: project.locationCode,
languageCode: project.languageCode,
createdAt: project.createdAt,
};
}
/**
* Resolves a market input into the columns to write. A location with no
* language snaps to that location's native language; the schemas forbid the
* reverse, so the pair is always resolvable without reading the stored row.
*/
function resolveMarketInput(input: {
locationCode?: number;
languageCode?: string;
}): { locationCode: number; languageCode: string } | undefined {
if (input.locationCode == null) return undefined;
const locationCode = input.locationCode;
const languageCode = input.languageCode ?? getLanguageCode(locationCode);
assertLanguageForLocation(locationCode, languageCode);
return { locationCode, languageCode };
}
// The projects table's only unique index guards the auto-created ("Default",
// null) singleton. A UNIQUE violation while writing exactly that name/domain
// therefore means one already exists — gating on the input (not just the error
@ -67,6 +92,7 @@ export async function createProject(
organizationId,
input.name,
input.domain,
resolveMarketInput(input),
);
return mapProject(row);
} catch (error) {
@ -85,7 +111,11 @@ export async function updateProject(
const row = await ProjectRepository.updateProject(
input.projectId,
organizationId,
{ name: input.name, domain: input.domain },
{
name: input.name,
domain: input.domain,
market: resolveMarketInput(input),
},
);
return mapProject(row);
} catch (error) {
@ -96,6 +126,24 @@ export async function updateProject(
}
}
/**
* Sets a project's default market on its own, for surfaces that only ask for
* the market (onboarding). Writing just these two columns keeps the write from
* echoing a name/domain the caller never edited.
*/
export async function setProjectMarket(
organizationId: string,
input: SetProjectMarketInput,
) {
assertLanguageForLocation(input.locationCode, input.languageCode);
const row = await ProjectRepository.updateProjectMarket(
input.projectId,
organizationId,
{ locationCode: input.locationCode, languageCode: input.languageCode },
);
return mapProject(row);
}
export async function archiveProject(
organizationId: string,
input: ArchiveProjectInput,

38
src/server/features/rank-tracking/services/RankTrackingService.test.ts
View File

@ -29,6 +29,7 @@ const archivedConfig = {
const baseInput = {
projectId: "project_1",
projectMarket: { locationCode: 2704, languageCode: "vi" },
domain: "acme.com",
locationCode: 2840,
languageCode: "es",
@ -154,4 +155,41 @@ describe("RankTrackingService.createConfig", () => {
}),
);
});
it("uses the project's market when location and language are omitted", async () => {
mocks.getConfigByProjectDomainLocation.mockResolvedValue(null);
mocks.getConfigsForProject.mockResolvedValue([]);
mocks.createConfig.mockResolvedValue(undefined);
const { RankTrackingService } = await import("./RankTrackingService");
await RankTrackingService.createConfig({
projectId: "project_1",
projectMarket: { locationCode: 2704, languageCode: "vi" },
domain: "acme.com",
serpDepth: 40,
});
expect(mocks.createConfig).toHaveBeenCalledWith(
expect.objectContaining({ locationCode: 2704, languageCode: "vi" }),
);
});
it("snaps the language when only location overrides the project market", async () => {
mocks.getConfigByProjectDomainLocation.mockResolvedValue(null);
mocks.getConfigsForProject.mockResolvedValue([]);
mocks.createConfig.mockResolvedValue(undefined);
const { RankTrackingService } = await import("./RankTrackingService");
await RankTrackingService.createConfig({
projectId: "project_1",
projectMarket: { locationCode: 2704, languageCode: "vi" },
domain: "acme.com",
locationCode: 2276,
serpDepth: 40,
});
expect(mocks.createConfig).toHaveBeenCalledWith(
expect.objectContaining({ locationCode: 2276, languageCode: "de" }),
);
});
});

11
src/server/features/rank-tracking/services/RankTrackingService.ts
View File

@ -22,6 +22,7 @@ import {
MAX_KEYWORDS_PER_CONFIG,
MAX_CONFIGS_PER_PROJECT,
} from "@/shared/rank-tracking";
import { resolveMarket } from "@/shared/keyword-locations";
// ---------------------------------------------------------------------------
// Config
@ -29,6 +30,7 @@ import {
async function createConfig(input: {
projectId: string;
projectMarket: { locationCode: number; languageCode: string };
domain: string;
locationCode?: number;
languageCode?: string;
@ -39,7 +41,10 @@ async function createConfig(input: {
}) {
const normalizedDomain = normalizeDomain(input.domain);
const locationCode = input.locationCode ?? 2840;
const { locationCode, languageCode } = resolveMarket(
input,
input.projectMarket,
);
const scheduleInterval = input.scheduleInterval ?? "weekly";
const nextCheckAt = isScheduledRankTrackingInterval(scheduleInterval)
? computeNextCheckAt(scheduleInterval)
@ -82,7 +87,7 @@ async function createConfig(input: {
if (existing) {
await RankTrackingRepository.updateConfig(existing.id, input.projectId, {
isActive: true,
languageCode: input.languageCode ?? "en",
languageCode,
devices: input.devices ?? "both",
serpDepth: input.serpDepth,
scheduleInterval,
@ -102,7 +107,7 @@ async function createConfig(input: {
projectId: input.projectId,
domain: normalizedDomain,
locationCode,
languageCode: input.languageCode ?? "en",
languageCode,
locationName,
devices: input.devices ?? "both",
serpDepth: input.serpDepth,

43
src/server/lib/market.ts Normal file
View File

@ -0,0 +1,43 @@
import { AppError } from "@/server/lib/errors";
import {
DEFAULT_LOCATION_CODE,
getKeywordDataProvider,
getLanguageOptions,
isLanguageServedForLocation,
} from "@/shared/keyword-locations";
/**
* Guards Labs-backed tools (domain analytics) against locations we serve
* from Google Ads keyword data only.
*/
export function assertLabsLocationCode(locationCode: number | undefined) {
if (locationCode != null && getKeywordDataProvider(locationCode) !== "labs") {
throw new AppError(
"VALIDATION_ERROR",
"Domain analytics is not available for this country. Keyword research and rank tracking work; domain-level data is limited to DataForSEO Labs locations.",
);
}
}
/**
* Guards Labs-backed callers against a language DataForSEO doesn't serve for
* the chosen location. A mismatched pair (e.g. language_code="ru" for the
* United States) is otherwise rejected as an opaque *charged* "Invalid Field:
* 'language_code'." task failure, so validate the pair first (cost 0).
*/
export function assertLanguageForLocation(
locationCode: number | undefined,
languageCode: string | undefined,
) {
if (languageCode == null) return;
const resolvedLocation = locationCode ?? DEFAULT_LOCATION_CODE;
if (isLanguageServedForLocation(resolvedLocation, languageCode)) return;
throw new AppError(
"VALIDATION_ERROR",
`Language '${languageCode}' is not available for this location. Available: ${getLanguageOptions(
resolvedLocation,
)
.map((option) => option.code)
.join(", ")}.`,
);
}

10
src/server/mcp/project-auth.test.ts
View File

@ -46,6 +46,8 @@ describe("withMcpProjectAuth", () => {
mocks.getProjectForOrganization.mockResolvedValue({
id: "project_123",
name: "Test",
locationCode: 2840,
languageCode: "en",
});
});
@ -64,7 +66,7 @@ describe("withMcpProjectAuth", () => {
);
});
it("passes auth, baseUrl, and billing context to the wrapped handler", async () => {
it("passes auth, baseUrl, billing, and project context to the wrapped handler", async () => {
const { withMcpProjectAuth } = await import("@/server/mcp/project-auth");
const handler = vi.fn().mockReturnValue("ok");
@ -90,6 +92,12 @@ describe("withMcpProjectAuth", () => {
organizationId: "org_123",
projectId: "project_123",
},
project: {
id: "project_123",
name: "Test",
locationCode: 2840,
languageCode: "en",
},
},
);
});

3
src/server/mcp/project-auth.ts
View File

@ -28,6 +28,9 @@ async function requireProjectAccess(extra: ToolExtra, projectId: string) {
auth,
baseUrl,
billing: buildBillingCustomer(auth, projectId),
// The row is already fetched for the auth gate; exposing it lets tools
// fall back to the project's default market without another query.
project,
};
}

53
src/server/mcp/schemas.ts
View File

@ -1,13 +1,7 @@
import { z } from "zod";
import { AppError } from "@/server/lib/errors";
import {
getKeywordDataProvider,
getLanguageOptions,
isSupportedLanguageCode,
} from "@/shared/keyword-locations";
import { isSupportedLanguageCode } from "@/shared/keyword-locations";
export const DEFAULT_LOCATION_CODE = 2840;
export const DEFAULT_LANGUAGE_CODE = "en";
export const projectIdSchema = z
.string()
@ -21,52 +15,15 @@ export const locationCodeSchema = z
.int()
.positive()
.describe(
"DataForSEO location code. Defaults to 2840 (United States). See dataforseo.com/help-center/locations. Some countries (e.g. Iceland, 2352) are served from Google Ads data: keyword volume/CPC/trends work, but keyword difficulty, search intent, and domain analytics are unavailable.",
"DataForSEO location code. Defaults to the project's default market (see list_projects; editable in project settings). See dataforseo.com/help-center/locations. Some countries (e.g. Iceland, 2352) are served from Google Ads data: keyword volume/CPC/trends work, but keyword difficulty, search intent, and domain analytics are unavailable.",
);
/**
* Guards Labs-backed tools (domain analytics) against locations we serve
* from Google Ads keyword data only.
*/
export function assertLabsLocationCode(locationCode: number | undefined) {
if (locationCode != null && getKeywordDataProvider(locationCode) !== "labs") {
throw new AppError(
"VALIDATION_ERROR",
"Domain analytics is not available for this country. Keyword research and rank tracking work; domain-level data is limited to DataForSEO Labs locations.",
);
}
}
/**
* Guards Labs-backed tools against a language DataForSEO doesn't serve for the
* chosen location. A mismatched pair (e.g. language_code="ru" for the United
* States) is otherwise rejected as an opaque *charged* "Invalid Field:
* 'language_code'." task failure, so validate the pair first (cost 0). Only
* Labs locations have authoritative per-location language lists; Google Ads
* locations are left to the metering safety net.
*/
export function assertLanguageForLocation(
locationCode: number | undefined,
languageCode: string | undefined,
) {
if (languageCode == null) return;
const resolvedLocation = locationCode ?? DEFAULT_LOCATION_CODE;
if (getKeywordDataProvider(resolvedLocation) !== "labs") return;
const options = getLanguageOptions(resolvedLocation);
if (!options.some((option) => option.code === languageCode)) {
throw new AppError(
"VALIDATION_ERROR",
`Language '${languageCode}' is not available for this location. Available: ${options
.map((option) => option.code)
.join(", ")}.`,
);
}
}
export const languageCodeSchema = z
.string()
.refine(isSupportedLanguageCode, {
message:
"Unsupported language code. Use a supported code such as 'en', 'es', 'de', or 'fr'.",
})
.describe("Language code (e.g. 'en', 'es', 'fr'). Defaults to 'en'.");
.describe(
"Language code (e.g. 'en', 'es', 'vi'). Defaults to the project's default market language (see list_projects).",
);

6
src/server/mcp/tools/dataforseo-research-tools.google-ads.test.ts
View File

@ -62,7 +62,11 @@ describe("get_keyword_metrics for Google-Ads-only locations", () => {
vi.resetModules();
mocks.createDataforseoClient.mockReset();
mocks.getProjectForOrganization.mockReset();
mocks.getProjectForOrganization.mockResolvedValue({ id: "project_1" });
mocks.getProjectForOrganization.mockResolvedValue({
id: "project_1",
locationCode: 2840,
languageCode: "en",
});
});
it("serves Iceland from adsSearchVolume without KD/intent", async () => {

114
src/server/mcp/tools/dataforseo-research-tools.market.test.ts Normal file
View File

@ -0,0 +1,114 @@
import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
import type { ToolExtra } from "@/server/mcp/context";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { MCP_AUTH_CONTEXT_PROP } from "@/server/mcp/context";
// Market resolution for get_ranked_keywords: the explicit country selector and
// the project's default-market fallback (projects.locationCode/languageCode).
// find_serp_competitors resolves through the same resolveMarketSelector.
const mocks = vi.hoisted(() => ({
createDataforseoClient: vi.fn(),
getProjectForOrganization: vi.fn(),
}));
vi.mock("cloudflare:workers", () => ({ env: {} }));
vi.mock("@/server/lib/dataforseo", () => ({
createDataforseoClient: mocks.createDataforseoClient,
fetchKeywordMetricsForList: vi.fn(),
}));
vi.mock("@/server/features/projects/services/ProjectService", () => ({
ProjectService: {
getProjectForOrganization: mocks.getProjectForOrganization,
},
}));
const authContext = {
userId: "user_123",
userEmail: "alice@example.com",
organizationId: "org_123",
clientId: "client_123",
scopes: ["mcp"],
audience: "https://open-seo.test/mcp",
subject: "user_123",
baseUrl: "https://open-seo.test",
};
const toolExtra: ToolExtra = {
signal: new AbortController().signal,
requestId: 1,
sendNotification: vi.fn(),
sendRequest: vi.fn(),
authInfo: {
token: "token",
clientId: "client_123",
scopes: ["mcp"],
resource: new URL("https://open-seo.test/mcp"),
extra: { [MCP_AUTH_CONTEXT_PROP]: authContext },
} satisfies AuthInfo,
};
function setProject(market: { locationCode: number; languageCode: string }) {
mocks.getProjectForOrganization.mockResolvedValue({
id: "project_1",
name: "Test",
domain: null,
createdAt: "2026-01-01T00:00:00.000Z",
...market,
});
}
async function runRankedKeywords(args: { market?: { country: "US" } }) {
const rankedKeywords = vi.fn().mockResolvedValue({
items: [],
totalCount: 0,
});
mocks.createDataforseoClient.mockReturnValue({
domain: { rankedKeywords },
});
const { getRankedKeywordsTool } = await import("./dataforseo-research-tools");
await getRankedKeywordsTool.handler(
{ projectId: "project_1", target: "acmeexample.com", ...args },
toolExtra,
);
return rankedKeywords;
}
describe("market resolution for Labs tools", () => {
beforeEach(() => {
vi.resetModules();
mocks.createDataforseoClient.mockReset();
mocks.getProjectForOrganization.mockReset();
setProject({ locationCode: 2840, languageCode: "en" });
});
it("keeps the US when market is explicit even for a non-US project", async () => {
setProject({ locationCode: 2704, languageCode: "vi" });
const rankedKeywords = await runRankedKeywords({
market: { country: "US" },
});
expect(rankedKeywords).toHaveBeenCalledWith(
expect.objectContaining({ locationCode: 2840, languageCode: "en" }),
);
});
it("follows the project's default market when the market object is omitted", async () => {
setProject({ locationCode: 2704, languageCode: "vi" });
const rankedKeywords = await runRankedKeywords({});
expect(rankedKeywords).toHaveBeenCalledWith(
expect.objectContaining({ locationCode: 2704, languageCode: "vi" }),
);
});
it("falls back to the US when the project market is not Labs-served", async () => {
// Iceland (2352) is served from Google Ads data; the Labs-only market
// tools must not inherit it.
setProject({ locationCode: 2352, languageCode: "en" });
const rankedKeywords = await runRankedKeywords({});
expect(rankedKeywords).toHaveBeenCalledWith(
expect.objectContaining({ locationCode: 2840, languageCode: "en" }),
);
});
});

8
src/server/mcp/tools/dataforseo-research-tools.test.ts
View File

@ -64,12 +64,18 @@ function textOf(result: {
return first?.type === "text" ? (first.text ?? "") : "";
}
const usProjectRow = {
id: "project_1",
locationCode: 2840,
languageCode: "en",
};
describe("DataForSEO research MCP tools", () => {
beforeEach(() => {
vi.resetModules();
mocks.createDataforseoClient.mockReset();
mocks.getProjectForOrganization.mockReset();
mocks.getProjectForOrganization.mockResolvedValue({ id: "project_1" });
mocks.getProjectForOrganization.mockResolvedValue(usProjectRow);
});
it("searches local businesses without running rankings or Q&A", async () => {

51
src/server/mcp/tools/dataforseo-research-tools.ts
View File

@ -17,10 +17,10 @@ import {
readPath,
type McpTableColumn,
} from "@/server/mcp/table";
import { resolveLabsMarket, resolveMarket } from "@/shared/keyword-locations";
import { assertLanguageForLocation } from "@/server/lib/market";
import {
DEFAULT_LANGUAGE_CODE,
DEFAULT_LOCATION_CODE,
assertLanguageForLocation,
languageCodeSchema,
locationCodeSchema,
projectIdSchema,
@ -46,10 +46,14 @@ const marketSchema = z
country: z
.enum(["US", "USA", "United States", "United States of America"])
.optional()
.describe("Country selector. Only the United States is supported."),
.describe(
"Country selector. Only the United States can be selected explicitly.",
),
})
.optional()
.describe("Optional United States market object. Defaults to United States.");
.describe(
"Optional market object. Omitted = the project's default market (United States unless the project overrides it).",
);
const nearSchema = z
.object({
@ -344,10 +348,20 @@ type GetGoogleBusinessQuestionsArgs = z.infer<
const QUESTIONS_ANSWERS_MIN_RADIUS = 200;
const QUESTIONS_ANSWERS_MAX_RADIUS = 199999;
function resolveMarketLocationCode(_market: Market | undefined): number {
// The Zod enum on market.country already restricts values to United States
// variants, so no other country can reach this code path.
return DEFAULT_LOCATION_CODE;
/**
* Resolves the market selector to a Labs location + language. An explicit
* country wins; omitted inherits the project's default via resolveLabsMarket,
* which keeps these Labs-only tools off an Ads-served project market.
*/
function resolveMarketSelector(
market: Market | undefined,
project: { locationCode: number; languageCode: string },
): { locationCode: number; languageCode: string } {
if (market?.country != null) {
// The Zod enum already restricts explicit values to United States variants.
return { locationCode: DEFAULT_LOCATION_CODE, languageCode: "en" };
}
return resolveLabsMarket({}, project);
}
function formatCoordinate(value: number): string {
@ -594,10 +608,11 @@ export const getRankedKeywordsTool = {
handler: withMcpProjectAuth(async (args: GetRankedKeywordsArgs, context) => {
const client = createDataforseoClient(context.billing);
const targetIsPage = /^https?:\/\//.test(args.target);
const market = resolveMarketSelector(args.market, context.project);
const keywords = await client.domain.rankedKeywords({
target: args.target,
locationCode: resolveMarketLocationCode(args.market),
languageCode: DEFAULT_LANGUAGE_CODE,
locationCode: market.locationCode,
languageCode: market.languageCode,
limit: args.limit ?? 50,
offset: args.offset,
orderBy: sortOrderByRankedMode(args.sortBy),
@ -693,7 +708,7 @@ export const getLocalSerpResultsTool = {
const results = await client.serp.local({
keyword: args.keyword,
locationCoordinate: formatLocalSerpCoordinate(args.near),
languageCode: args.languageCode ?? DEFAULT_LANGUAGE_CODE,
languageCode: args.languageCode ?? context.project.languageCode,
searchType: args.searchType ?? "maps",
device: args.device ?? "desktop",
depth: args.depth ?? 20,
@ -736,7 +751,7 @@ export const getGoogleBusinessQuestionsTool = {
const questions = await client.business.questionsAnswers({
keyword: args.keyword,
locationCoordinate: formatQuestionsAnswersCoordinate(args.near),
languageCode: args.languageCode ?? DEFAULT_LANGUAGE_CODE,
languageCode: args.languageCode ?? context.project.languageCode,
depth: args.depth ?? 20,
});
@ -773,10 +788,11 @@ export const findSerpCompetitorsTool = {
handler: withMcpProjectAuth(
async (args: FindSerpCompetitorsArgs, context) => {
const client = createDataforseoClient(context.billing);
const market = resolveMarketSelector(args.market, context.project);
const competitors = await client.labs.serpCompetitors({
keywords: args.keywords,
locationCode: resolveMarketLocationCode(args.market),
languageCode: DEFAULT_LANGUAGE_CODE,
locationCode: market.locationCode,
languageCode: market.languageCode,
itemTypes: args.resultTypes ?? ["organic", "local_pack"],
includeSubdomains: args.includeSubdomains,
limit: args.limit ?? 50,
@ -829,10 +845,11 @@ export const getKeywordMetricsTool = {
},
},
handler: withMcpProjectAuth(async (args: GetKeywordMetricsArgs, context) => {
assertLanguageForLocation(args.locationCode, args.languageCode);
const { locationCode, languageCode } = resolveMarket(args, context.project);
// Assert against the RESOLVED pair: an explicit language with an omitted
// location must validate against the project's default location.
assertLanguageForLocation(locationCode, languageCode);
const client = createDataforseoClient(context.billing);
const locationCode = args.locationCode ?? DEFAULT_LOCATION_CODE;
const languageCode = args.languageCode ?? DEFAULT_LANGUAGE_CODE;
const metrics = await fetchKeywordMetricsForList(client, {
keywords: args.keywords,
locationCode,

17
src/server/mcp/tools/get-domain-keyword-suggestions.ts
View File

@ -7,16 +7,17 @@ import {
optionalMetaOutputSchema,
} from "@/server/mcp/output-schemas";
import { withMcpProjectAuth } from "@/server/mcp/project-auth";
import { resolveLabsMarket } from "@/shared/keyword-locations";
import {
formatMcpTable,
readPath,
type McpTableColumn,
} from "@/server/mcp/table";
import {
DEFAULT_LANGUAGE_CODE,
DEFAULT_LOCATION_CODE,
assertLabsLocationCode,
assertLanguageForLocation,
} from "@/server/lib/market";
import {
languageCodeSchema,
locationCodeSchema,
projectIdSchema,
@ -59,13 +60,17 @@ export const getDomainKeywordSuggestionsTool = {
},
},
handler: withMcpProjectAuth(async (args: Args, context) => {
assertLabsLocationCode(args.locationCode);
assertLanguageForLocation(args.locationCode, args.languageCode);
const { locationCode, languageCode } = resolveLabsMarket(
args,
context.project,
);
assertLabsLocationCode(locationCode);
assertLanguageForLocation(locationCode, languageCode);
const keywords = await DomainService.getSuggestedKeywords(
{
domain: args.domain,
locationCode: args.locationCode ?? DEFAULT_LOCATION_CODE,
languageCode: args.languageCode ?? DEFAULT_LANGUAGE_CODE,
locationCode,
languageCode,
organizationId: context.auth.organizationId,
projectId: args.projectId,
},

17
src/server/mcp/tools/get-domain-overview.ts
View File

@ -4,11 +4,12 @@ import { mcpResponse } from "@/server/mcp/formatters";
import { buildProjectMeta } from "@/server/mcp/context";
import { optionalMetaOutputSchema } from "@/server/mcp/output-schemas";
import { withMcpProjectAuth } from "@/server/mcp/project-auth";
import { resolveLabsMarket } from "@/shared/keyword-locations";
import {
DEFAULT_LANGUAGE_CODE,
DEFAULT_LOCATION_CODE,
assertLabsLocationCode,
assertLanguageForLocation,
} from "@/server/lib/market";
import {
languageCodeSchema,
locationCodeSchema,
projectIdSchema,
@ -52,15 +53,19 @@ export const getDomainOverviewTool = {
},
},
handler: withMcpProjectAuth(async (args: Args, context) => {
assertLabsLocationCode(args.locationCode);
assertLanguageForLocation(args.locationCode, args.languageCode);
const { locationCode, languageCode } = resolveLabsMarket(
args,
context.project,
);
assertLabsLocationCode(locationCode);
assertLanguageForLocation(locationCode, languageCode);
const result = await DomainService.getOverview(
{
projectId: args.projectId,
domain: args.domain,
includeSubdomains: args.includeSubdomains,
locationCode: args.locationCode ?? DEFAULT_LOCATION_CODE,
languageCode: args.languageCode ?? DEFAULT_LANGUAGE_CODE,
locationCode,
languageCode,
},
context.billing,
);

7
src/server/mcp/tools/get-serp-results.ts
View File

@ -4,10 +4,9 @@ import { mcpResponse } from "@/server/mcp/formatters";
import { buildProjectMeta } from "@/server/mcp/context";
import { optionalMetaOutputSchema } from "@/server/mcp/output-schemas";
import { withMcpProjectAuth } from "@/server/mcp/project-auth";
import { resolveMarket } from "@/shared/keyword-locations";
import { formatMcpTable, type McpTableColumn } from "@/server/mcp/table";
import {
DEFAULT_LANGUAGE_CODE,
DEFAULT_LOCATION_CODE,
languageCodeSchema,
locationCodeSchema,
projectIdSchema,
@ -95,14 +94,12 @@ export const getSerpResultsTool = {
},
handler: withMcpProjectAuth(async (args: Args, context) => {
const client = createDataforseoClient(context.billing);
const results = await Promise.all(
args.queries.map(async (q) => {
try {
const items = await client.serp.live({
keyword: q.keyword,
locationCode: q.locationCode ?? DEFAULT_LOCATION_CODE,
languageCode: q.languageCode ?? DEFAULT_LANGUAGE_CODE,
...resolveMarket(q, context.project),
});
// Trim noise — return only essentials per item.
const trimmed = items.slice(0, 20).map((item) => ({

9
src/server/mcp/tools/list-projects.ts
View File

@ -13,7 +13,7 @@ export const listProjectsTool = {
config: {
title: "List projects",
description:
"Lists all projects in the user's organization. Uses no credits — does not call DataForSEO. Use this whenever you need a `projectId` for another OpenSEO tool. Returns an array of {id, name, domain}; pass the `id` value as `projectId`.",
"Lists all projects in the user's organization. Uses no credits — does not call DataForSEO. Use this whenever you need a `projectId` for another OpenSEO tool. Returns an array of {id, name, domain, locationCode, languageCode}; pass the `id` value as `projectId`. locationCode/languageCode are the project's default market — tools fall back to them when a call omits location/language args.",
inputSchema: {} as Record<string, never>,
outputSchema: {
projects: z.array(
@ -22,6 +22,8 @@ export const listProjectsTool = {
id: z.string(),
name: z.string(),
domain: z.string().nullable().optional(),
locationCode: z.number(),
languageCode: z.string(),
url: z.string(),
})
.passthrough(),
@ -41,7 +43,8 @@ export const listProjectsTool = {
projects.length === 0
? ["No projects yet. Create one in the dashboard."]
: projects.map(
(p) => `- ${p.id} ${p.name}${p.domain ? ` (${p.domain})` : ""}`,
(p) =>
`- ${p.id} ${p.name}${p.domain ? ` (${p.domain})` : ""} market:${p.locationCode}/${p.languageCode}`,
);
return mcpResponse({
text: `Projects (${projects.length}):\n${lines.join("\n")}`,
@ -54,6 +57,8 @@ export const listProjectsTool = {
id: p.id,
name: p.name,
domain: p.domain,
locationCode: p.locationCode,
languageCode: p.languageCode,
url: buildDashboardUrl(baseUrl, `/p/${p.id}`),
})),
},

6
src/server/mcp/tools/output-schema-validation.test.ts
View File

@ -99,7 +99,11 @@ const backlinkPage = {
beforeEach(() => {
mocks.getProjectForOrganization.mockReset();
mocks.profileBacklinksPage.mockReset();
mocks.getProjectForOrganization.mockResolvedValue({ id: "project_123" });
mocks.getProjectForOrganization.mockResolvedValue({
id: "project_123",
locationCode: 2840,
languageCode: "en",
});
});
describe("DataForSEO research tool output schemas", () => {

15
src/server/mcp/tools/research-keywords.ts
View File

@ -7,11 +7,10 @@ import {
optionalMetaOutputSchema,
} from "@/server/mcp/output-schemas";
import { withMcpProjectAuth } from "@/server/mcp/project-auth";
import { resolveMarket } from "@/shared/keyword-locations";
import { formatMcpTable, type McpTableColumn } from "@/server/mcp/table";
import { assertLanguageForLocation } from "@/server/lib/market";
import {
DEFAULT_LANGUAGE_CODE,
DEFAULT_LOCATION_CODE,
assertLanguageForLocation,
languageCodeSchema,
locationCodeSchema,
projectIdSchema,
@ -108,13 +107,17 @@ export const researchKeywordsTool = {
const results = await Promise.all(
args.seeds.map(async (item) => {
try {
assertLanguageForLocation(item.locationCode, item.languageCode);
const { locationCode, languageCode } = resolveMarket(
item,
context.project,
);
assertLanguageForLocation(locationCode, languageCode);
const data = await KeywordResearchService.research(
{
projectId: args.projectId,
keywords: [item.seed],
locationCode: item.locationCode ?? DEFAULT_LOCATION_CODE,
languageCode: item.languageCode ?? DEFAULT_LANGUAGE_CODE,
locationCode,
languageCode,
resultLimit: args.resultLimit ?? 150,
mode: "auto",
clickstream: args.includeClickstreamData ?? false,

6
src/server/mcp/tools/save-keywords.ts
View File

@ -4,9 +4,8 @@ import { mcpResponse } from "@/server/mcp/formatters";
import { buildProjectMeta } from "@/server/mcp/context";
import { optionalMetaOutputSchema } from "@/server/mcp/output-schemas";
import { withMcpProjectAuth } from "@/server/mcp/project-auth";
import { resolveMarket } from "@/shared/keyword-locations";
import {
DEFAULT_LANGUAGE_CODE,
DEFAULT_LOCATION_CODE,
languageCodeSchema,
locationCodeSchema,
projectIdSchema,
@ -66,8 +65,7 @@ export const saveKeywordsTool = {
throw new Error("Replacement tags are required when tagMode is replace.");
}
const locationCode = args.locationCode ?? DEFAULT_LOCATION_CODE;
const languageCode = args.languageCode ?? DEFAULT_LANGUAGE_CODE;
const { locationCode, languageCode } = resolveMarket(args, context.project);
await KeywordResearchService.saveKeywords({
projectId: args.projectId,

6
src/server/mcp/tools/saved-keywords-tools.test.ts
View File

@ -51,7 +51,11 @@ describe("saved keyword MCP tools", () => {
beforeEach(() => {
vi.resetModules();
mocks.getProjectForOrganization.mockReset();
mocks.getProjectForOrganization.mockResolvedValue({ id: "project_1" });
mocks.getProjectForOrganization.mockResolvedValue({
id: "project_1",
locationCode: 2840,
languageCode: "en",
});
mocks.getSavedKeywords.mockReset();
mocks.saveKeywords.mockReset();
});

6
src/server/mcp/tools/search-console-tools.test.ts
View File

@ -76,7 +76,11 @@ const toolExtra: ToolExtra = {
describe("search console MCP tools", () => {
beforeEach(() => {
mocks.getProjectForOrganization.mockReset();
mocks.getProjectForOrganization.mockResolvedValue({ id: "project_1" });
mocks.getProjectForOrganization.mockResolvedValue({
id: "project_1",
locationCode: 2840,
languageCode: "en",
});
mocks.isHostedServerAuthMode.mockReset();
mocks.isHostedServerAuthMode.mockResolvedValue(true);
mocks.hasSelfHostedGscConfig.mockReset();

6
src/server/mcp/tools/tool-text-output.test.ts
View File

@ -90,7 +90,11 @@ describe("MCP tool text output (service-backed tools)", () => {
beforeEach(() => {
vi.resetModules();
for (const mock of Object.values(mocks)) mock.mockReset();
mocks.getProjectForOrganization.mockResolvedValue({ id: "project_1" });
mocks.getProjectForOrganization.mockResolvedValue({
id: "project_1",
locationCode: 2840,
languageCode: "en",
});
});
it("research_keywords renders every keyword row in the text table", async () => {

47
src/serverFunctions/domain.ts
View File

@ -7,6 +7,7 @@ import {
domainPagesPageRequestSchema,
} from "@/types/schemas/domain";
import { DomainService } from "@/server/features/domain/services/DomainService";
import { resolveLabsMarket } from "@/shared/keyword-locations";
function shouldUseDomainE2eFixtures() {
return import.meta.env.VITE_E2E_DOMAIN_FIXTURES === "1";
@ -20,18 +21,17 @@ export const getDomainOverview = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(domainOverviewSchema)
.handler(async ({ data, context }) => {
const input = {
...data,
...resolveLabsMarket(data, context.project),
projectId: context.projectId,
};
if (shouldUseDomainE2eFixtures()) {
const fixtures = await getDomainE2eFixtures();
return fixtures.getFixtureOverview(data.domain);
return fixtures.getFixtureOverview(input.domain);
}
return DomainService.getOverview(
{
...data,
projectId: context.projectId,
},
context,
);
return DomainService.getOverview(input, context);
});
export const getDomainKeywordSuggestions = createServerFn({ method: "POST" })
@ -41,6 +41,7 @@ export const getDomainKeywordSuggestions = createServerFn({ method: "POST" })
DomainService.getSuggestedKeywords(
{
...data,
...resolveLabsMarket(data, context.project),
organizationId: context.organizationId,
projectId: context.projectId,
},
@ -52,34 +53,32 @@ export const getDomainKeywordsPage = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(domainKeywordsPageRequestSchema)
.handler(async ({ data, context }) => {
const input = {
...data,
...resolveLabsMarket(data, context.project),
projectId: context.projectId,
};
if (shouldUseDomainE2eFixtures()) {
const fixtures = await getDomainE2eFixtures();
return fixtures.getFixtureKeywordsPage(data);
return fixtures.getFixtureKeywordsPage(input);
}
return DomainService.getKeywordsPage(
{
...data,
projectId: context.projectId,
},
context,
);
return DomainService.getKeywordsPage(input, context);
});
export const getDomainPagesPage = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(domainPagesPageRequestSchema)
.handler(async ({ data, context }) => {
const input = {
...data,
...resolveLabsMarket(data, context.project),
projectId: context.projectId,
};
if (shouldUseDomainE2eFixtures()) {
const fixtures = await getDomainE2eFixtures();
return fixtures.getFixturePagesPage(data);
return fixtures.getFixturePagesPage(input);
}
return DomainService.getPagesPage(
{
...data,
projectId: context.projectId,
},
context,
);
return DomainService.getPagesPage(input, context);
});

18
src/serverFunctions/keywords.ts
View File

@ -13,6 +13,7 @@ import {
} from "@/types/schemas/keywords";
import { KeywordResearchService } from "@/server/features/keywords/services/KeywordResearchService";
import { requireProjectContext } from "@/serverFunctions/middleware";
import { resolveMarket } from "@/shared/keyword-locations";
function shouldUseKeywordE2eFixtures() {
return import.meta.env.VITE_E2E_KEYWORD_FIXTURES === "1";
@ -26,18 +27,17 @@ export const researchKeywords = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(researchKeywordsSchema)
.handler(async ({ data, context }) => {
const input = {
...data,
...resolveMarket(data, context.project),
projectId: context.projectId,
};
if (shouldUseKeywordE2eFixtures()) {
const fixtures = await getKeywordE2eFixtures();
return fixtures.getKeywordResearchFixture(data);
return fixtures.getKeywordResearchFixture(input);
}
return KeywordResearchService.research(
{
...data,
projectId: context.projectId,
},
context,
);
return KeywordResearchService.research(input, context);
});
export const saveKeywords = createServerFn({ method: "POST" })
@ -46,6 +46,7 @@ export const saveKeywords = createServerFn({ method: "POST" })
.handler(async ({ data, context }) => {
return KeywordResearchService.saveKeywords({
...data,
...resolveMarket(data, context.project),
projectId: context.projectId,
});
});
@ -126,6 +127,7 @@ export const getSerpAnalysis = createServerFn({ method: "POST" })
KeywordResearchService.getSerpAnalysis(
{
...data,
...resolveMarket(data, context.project),
projectId: context.projectId,
},
context,

8
src/serverFunctions/projects.ts
View File

@ -8,6 +8,7 @@ import {
archiveProjectSchema,
createProjectSchema,
restoreProjectSchema,
setProjectMarketSchema,
updateProjectSchema,
} from "@/types/schemas/projects";
import { z } from "zod";
@ -34,6 +35,13 @@ export const updateProject = createServerFn({ method: "POST" })
ProjectService.updateProject(context.organizationId, data),
);
export const setProjectMarket = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(setProjectMarketSchema)
.handler(async ({ data, context }) =>
ProjectService.setProjectMarket(context.organizationId, data),
);
export const archiveProject = createServerFn({ method: "POST" })
.middleware(requireProjectContext)
.validator(archiveProjectSchema)

1
src/serverFunctions/rank-tracking.ts
View File

@ -77,6 +77,7 @@ export const createRankTrackingConfig = createServerFn({ method: "POST" })
.handler(async ({ data, context }) => {
const result = await RankTrackingService.createConfig({
projectId: context.projectId,
projectMarket: context.project,
domain: data.domain,
locationCode: data.locationCode,
languageCode: data.languageCode,

75
src/shared/keyword-locations.test.ts
View File

@ -9,6 +9,8 @@ import {
isLabsLocationCode,
isSupportedLanguageCode,
isSupportedLocationCode,
resolveLabsMarket,
resolveMarket,
} from "./keyword-locations";
describe("keyword locations", () => {
@ -94,3 +96,76 @@ describe("formatLocationLabel", () => {
);
});
});
describe("resolveMarket", () => {
const vietnamProject = { locationCode: 2704, languageCode: "vi" };
it("falls back to the project's pair when nothing is supplied", () => {
expect(resolveMarket({}, vietnamProject)).toEqual({
locationCode: 2704,
languageCode: "vi",
});
});
it("snaps the language to a location override instead of borrowing the project's", () => {
// A Vietnam project querying Germany must not send Vietnamese.
expect(resolveMarket({ locationCode: 2276 }, vietnamProject)).toEqual({
locationCode: 2276,
languageCode: "de",
});
});
it("keeps the project language when the override matches the project location", () => {
const spanishUs = { locationCode: 2840, languageCode: "es" };
expect(resolveMarket({ locationCode: 2840 }, spanishUs)).toEqual({
locationCode: 2840,
languageCode: "es",
});
});
it("applies an explicit language to the project's location", () => {
expect(resolveMarket({ languageCode: "en" }, vietnamProject)).toEqual({
locationCode: 2704,
languageCode: "en",
});
});
it("uses both overrides verbatim", () => {
expect(
resolveMarket({ locationCode: 2276, languageCode: "en" }, vietnamProject),
).toEqual({ locationCode: 2276, languageCode: "en" });
});
});
describe("resolveLabsMarket", () => {
it("inherits a Labs-served project market like resolveMarket does", () => {
expect(
resolveLabsMarket({}, { locationCode: 2704, languageCode: "vi" }),
).toEqual({ locationCode: 2704, languageCode: "vi" });
});
it("falls back to the US when the project market is Google-Ads-served", () => {
// Iceland has no Labs data. The caller never picked it, so a Labs-only
// tool must not fail on it.
expect(
resolveLabsMarket({}, { locationCode: 2352, languageCode: "en" }),
).toEqual({ locationCode: 2840, languageCode: "en" });
});
it("falls back to the US when the project pair is not served", () => {
// Concurrent half-updates can leave a location/language pair Labs rejects;
// sending it would spend credits on a task that always fails.
expect(
resolveLabsMarket({}, { locationCode: 2276, languageCode: "vi" }),
).toEqual({ locationCode: 2840, languageCode: "en" });
});
it("leaves an explicit location alone so the caller's assert can reject it", () => {
expect(
resolveLabsMarket(
{ locationCode: 2352 },
{ locationCode: 2704, languageCode: "vi" },
),
).toMatchObject({ locationCode: 2352 });
});
});

66
src/shared/keyword-locations.ts
View File

@ -697,6 +697,66 @@ export function getLanguageCode(locationCode: number): string {
return LOCATION_LANGUAGE[locationCode] ?? "en";
}
/**
* Resolves a request's market against the project's default. The pair is
* resolved together: overriding only the location snaps the language to that
* location's default language, because the project's language was chosen for
* the project's own location and may not be valid — or sensible — for the
* override (e.g. a Vietnam project querying Germany must not default to
* Vietnamese).
*/
export function resolveMarket(
args: { locationCode?: number; languageCode?: string },
project: { locationCode: number; languageCode: string },
): { locationCode: number; languageCode: string } {
const locationCode = args.locationCode ?? project.locationCode;
const languageCode =
args.languageCode ??
(locationCode === project.locationCode
? project.languageCode
: getLanguageCode(locationCode));
return { locationCode, languageCode };
}
/**
* Whether DataForSEO serves this language for this location. Only Labs
* locations have authoritative per-location language lists; Google Ads
* locations are left to the metering safety net.
*/
export function isLanguageServedForLocation(
locationCode: number,
languageCode: string,
): boolean {
if (getKeywordDataProvider(locationCode) !== "labs") return true;
return getLanguageOptions(locationCode).some(
(option) => option.code === languageCode,
);
}
/**
* Resolves the market for a Labs-only tool. Same as resolveMarket, except a
* project default Labs cannot serve is replaced by the United States: the
* caller never chose that market, so rejecting the call would dead-end on a
* value it can't see — and passing the pair through would spend credits on a
* task DataForSEO rejects. An explicit location is left alone, so a caller that
* names an unserved country still fails loudly on its own assert.
*/
export function resolveLabsMarket(
args: { locationCode?: number; languageCode?: string },
project: { locationCode: number; languageCode: string },
): { locationCode: number; languageCode: string } {
const projectIsServed =
getKeywordDataProvider(project.locationCode) === "labs" &&
isLanguageServedForLocation(project.locationCode, project.languageCode);
return resolveMarket(
args,
projectIsServed
? project
: { locationCode: DEFAULT_LOCATION_CODE, languageCode: "en" },
);
}
/**
* Language codes DataForSEO accepts — the master LANGUAGE_OPTIONS list. Callers
* (e.g. MCP tools) can pass an arbitrary `language_code`; an unsupported one is
@ -738,9 +798,9 @@ const MULTI_LANGUAGE_LOCATIONS: Record<number, readonly string[]> = {
};
/**
* Languages to offer for a location's rank-tracking config. Restricts the
* global LANGUAGE_OPTIONS list to the languages DataForSEO supports for that
* country, so the picker isn't a wall of irrelevant options.
* Languages to offer for a location. Restricts the global LANGUAGE_OPTIONS
* list to the languages DataForSEO supports for that country, so a picker
* isn't a wall of irrelevant options.
*/
export function getLanguageOptions(
locationCode: number,

147
src/shared/keyword-locations.vendor-defaults.test.ts Normal file
View File

@ -0,0 +1,147 @@
import { describe, expect, it } from "vitest";
import {
LABS_LOCATION_OPTIONS,
getLanguageCode,
isLabsLocationCode,
} from "./keyword-locations";
/**
* DataForSEO's own default language for each Labs location: the language with
* the most keyword records, which is what Labs uses when a call omits
* language_code. Snapshot of the free
* GET /v3/dataforseo_labs/locations_and_languages, taken 2026-07-16.
*
* LOCATION_LANGUAGE is hand-maintained, so it can drift from what DataForSEO
* actually serves — a drifted entry sends the wrong-language data for a
* country without failing. Refresh this snapshot with:
*
* curl -s https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages \
* -H "Authorization: Basic $DATAFORSEO_API_KEY" \
* | jq -r '.tasks[0].result | sort_by(.location_code)[]
* | " \(.location_code): \"\(.available_languages | max_by(.keywords) | .language_code)\", // \(.location_name)"'
*
* Google-Ads-only countries are absent by design: Labs holds no data for them,
* so their language has no vendor answer to check against.
*/
const VENDOR_DEFAULT_LANGUAGE: Record<number, string> = {
2008: "sq", // Albania
2012: "fr", // Algeria
2024: "pt", // Angola
2031: "az", // Azerbaijan
2032: "es", // Argentina
2036: "en", // Australia
2040: "de", // Austria
2048: "ar", // Bahrain
2050: "bn", // Bangladesh
2051: "hy", // Armenia
2056: "nl", // Belgium
2068: "es", // Bolivia
2070: "bs", // Bosnia and Herzegovina
2076: "pt", // Brazil
2100: "bg", // Bulgaria
2104: "en", // Myanmar (Burma)
2116: "en", // Cambodia
2120: "fr", // Cameroon
2124: "en", // Canada
2144: "en", // Sri Lanka
2152: "es", // Chile
2158: "zh-TW", // Taiwan
2170: "es", // Colombia
2188: "es", // Costa Rica
2191: "hr", // Croatia
2196: "el", // Cyprus
2203: "cs", // Czechia
2208: "da", // Denmark
2218: "es", // Ecuador
2222: "es", // El Salvador
2233: "et", // Estonia
2246: "fi", // Finland
2250: "fr", // France
2276: "de", // Germany
2288: "en", // Ghana
2300: "el", // Greece
2320: "es", // Guatemala
2344: "zh-TW", // Hong Kong
2348: "hu", // Hungary
2356: "en", // India
2360: "id", // Indonesia
2372: "en", // Ireland
2376: "he", // Israel
2380: "it", // Italy
2384: "fr", // Cote d'Ivoire
2392: "ja", // Japan
2398: "ru", // Kazakhstan
2400: "ar", // Jordan
2404: "en", // Kenya
2410: "ko", // South Korea
2428: "lv", // Latvia
2440: "lt", // Lithuania
2458: "en", // Malaysia
2470: "en", // Malta
2484: "es", // Mexico
2492: "fr", // Monaco
2498: "ro", // Moldova
2504: "ar", // Morocco
2528: "nl", // Netherlands
2554: "en", // New Zealand
2558: "es", // Nicaragua
2566: "en", // Nigeria
2578: "nb", // Norway
2586: "en", // Pakistan
2591: "es", // Panama
2600: "es", // Paraguay
2604: "es", // Peru
2608: "en", // Philippines
2616: "pl", // Poland
2620: "pt", // Portugal
2642: "ro", // Romania
2682: "ar", // Saudi Arabia
2686: "fr", // Senegal
2688: "sr", // Serbia
2702: "en", // Singapore
2703: "sk", // Slovakia
2704: "vi", // Vietnam
2705: "sl", // Slovenia
2710: "en", // South Africa
2724: "es", // Spain
2752: "sv", // Sweden
2756: "de", // Switzerland
2764: "th", // Thailand
2784: "en", // United Arab Emirates
2788: "ar", // Tunisia
2792: "tr", // Turkiye
2804: "uk", // Ukraine
2807: "mk", // North Macedonia
2818: "ar", // Egypt
2826: "en", // United Kingdom
2840: "en", // United States
2854: "fr", // Burkina Faso
2858: "es", // Uruguay
2862: "es", // Venezuela
};
describe("getLanguageCode vs DataForSEO's Labs defaults", () => {
it("uses DataForSEO's default language for every Labs location", () => {
const drifted = Object.entries(VENDOR_DEFAULT_LANGUAGE)
.filter(([code, language]) => getLanguageCode(Number(code)) !== language)
.map(
([code, language]) =>
`${code}: ours=${getLanguageCode(Number(code))} vendor=${language}`,
);
expect(drifted).toEqual([]);
});
it("classifies every location DataForSEO serves from Labs as a Labs location", () => {
const misclassified = Object.entries(VENDOR_DEFAULT_LANGUAGE)
.filter(([code]) => !isLabsLocationCode(Number(code)))
.map(([code, language]) => `${code}: vendor serves ${language} via Labs`);
expect(misclassified).toEqual([]);
});
it("covers every Labs location we offer, so a new one can't skip the check", () => {
const unverified = LABS_LOCATION_OPTIONS.filter(
(option) => VENDOR_DEFAULT_LANGUAGE[option.code] == null,
).map((option) => `${option.code} ${option.label}`);
expect(unverified).toEqual([]);
});
});

16
src/types/schemas/domain.ts
View File

@ -59,8 +59,8 @@ export const domainOverviewSchema = z.object({
projectId: z.string().uuid(),
domain: z.string().min(1, "Domain is required").max(255),
includeSubdomains: z.boolean().default(true),
locationCode: z.number().int().positive().default(2840),
languageCode: z.string().min(2).max(8).default("en"),
locationCode: z.number().int().positive().optional(),
languageCode: z.string().min(2).max(8).optional(),
});
/* ------------------------------------------------------------------ */
@ -74,8 +74,8 @@ const domainTabs = ["keywords", "pages"] as const;
export const domainKeywordSuggestionsSchema = z.object({
projectId: z.string().uuid(),
domain: domainField,
locationCode: z.number().int().positive(),
languageCode: z.string().min(2).max(8),
locationCode: z.number().int().positive().optional(),
languageCode: z.string().min(2).max(8).optional(),
});
export const DOMAIN_KEYWORDS_PAGE_SIZES = [50, 100, 200] as const;
@ -119,8 +119,8 @@ export const domainKeywordsPageRequestSchema = z.object({
projectId: z.string().uuid(),
domain: z.string().min(1).max(255),
includeSubdomains: z.boolean().default(true),
locationCode: z.number().int().positive().default(2840),
languageCode: z.string().min(2).max(8).default("en"),
locationCode: z.number().int().positive().optional(),
languageCode: z.string().min(2).max(8).optional(),
page: z.number().int().positive().default(1),
pageSize: z
.number()
@ -141,8 +141,8 @@ export const domainPagesPageRequestSchema = z.object({
projectId: z.string().uuid(),
domain: z.string().min(1).max(255),
includeSubdomains: z.boolean().default(true),
locationCode: z.number().int().positive().default(2840),
languageCode: z.string().min(2).max(8).default("en"),
locationCode: z.number().int().positive().optional(),
languageCode: z.string().min(2).max(8).optional(),
page: z.number().int().positive().default(1),
pageSize: z
.number()

23
src/types/schemas/keywords.ts
View File

@ -18,8 +18,8 @@ const sortDirs = ["asc", "desc"] as const;
export const researchKeywordsSchema = z.object({
projectId: z.string().min(1),
keywords: z.array(z.string().min(1)).min(1).max(200),
locationCode: z.number().int().positive().default(2840),
languageCode: z.string().min(2).max(8).default("en"),
locationCode: z.number().int().positive().optional(),
languageCode: z.string().min(2).max(8).optional(),
resultLimit: z
.union([z.literal(150), z.literal(300), z.literal(500)])
.default(150),
@ -35,8 +35,8 @@ export const saveKeywordsSchema = z
.object({
projectId: z.string().min(1),
keywords: z.array(z.string().min(1)).min(1).max(500),
locationCode: z.number().int().positive().default(2840),
languageCode: z.string().min(2).max(8).default("en"),
locationCode: z.number().int().positive().optional(),
languageCode: z.string().min(2).max(8).optional(),
tags: z.array(savedKeywordTagSchema).max(20).optional(),
tagMode: z.enum(["append", "replace"]).optional(),
metrics: z
@ -149,6 +149,17 @@ export const refreshSavedKeywordMetricsSchema = z.object({
export type ResearchKeywordsInput = z.infer<typeof researchKeywordsSchema>;
export type SaveKeywordsInput = z.infer<typeof saveKeywordsSchema>;
type ResolvedMarket = { locationCode: number; languageCode: string };
export type ResolvedResearchKeywordsInput = Omit<
ResearchKeywordsInput,
keyof ResolvedMarket
> &
ResolvedMarket;
export type ResolvedSaveKeywordsInput = Omit<
SaveKeywordsInput,
keyof ResolvedMarket
> &
ResolvedMarket;
export type RemoveSavedKeywordsInput = z.infer<
typeof removeSavedKeywordsSchema
>;
@ -172,8 +183,8 @@ export type RefreshSavedKeywordMetricsInput = z.infer<
export const serpAnalysisSchema = z.object({
projectId: z.string().min(1),
keyword: z.string().min(1),
locationCode: z.number().int().positive().default(2840),
languageCode: z.string().min(2).max(8).default("en"),
locationCode: z.number().int().positive().optional(),
languageCode: z.string().min(2).max(8).optional(),
});
/* ------------------------------------------------------------------ */

39
src/types/schemas/projects.test.ts Normal file
View File

@ -0,0 +1,39 @@
import { describe, expect, it } from "vitest";
import { createProjectSchema, updateProjectSchema } from "./projects";
// The service derives a missing language from the location, so a language
// arriving on its own has nothing to validate against.
describe("project market fields", () => {
it("rejects a language with no location", () => {
expect(
updateProjectSchema.safeParse({
projectId: "project_1",
name: "Acme",
languageCode: "vi",
}).success,
).toBe(false);
expect(
createProjectSchema.safeParse({ name: "Acme", languageCode: "vi" })
.success,
).toBe(false);
});
it("accepts a location on its own, and a full pair", () => {
expect(
createProjectSchema.safeParse({ name: "Acme", locationCode: 2704 })
.success,
).toBe(true);
expect(
updateProjectSchema.safeParse({
projectId: "project_1",
name: "Acme",
locationCode: 2704,
languageCode: "vi",
}).success,
).toBe(true);
});
it("accepts a project with no market at all", () => {
expect(createProjectSchema.safeParse({ name: "Acme" }).success).toBe(true);
});
});

67
src/types/schemas/projects.ts
View File

@ -1,4 +1,8 @@
import { z } from "zod";
import {
isSupportedLanguageCode,
isSupportedLocationCode,
} from "@/shared/keyword-locations";
const projectNameField = z
.string()
@ -13,15 +17,63 @@ const projectDomainField = z
.transform((value) => value || undefined)
.optional();
export const createProjectSchema = z.object({
name: projectNameField,
domain: projectDomainField,
});
// Default market for the project's data calls. The location/language PAIR is
// validated in the service (an update may change one side and needs the
// stored row for the other).
const projectLocationCodeField = z
.number()
.int()
.refine(isSupportedLocationCode, "Unsupported DataForSEO location code")
.optional();
export const updateProjectSchema = z.object({
const projectLanguageCodeField = z
.string()
.refine(isSupportedLanguageCode, "Unsupported language code")
.optional();
// A language on its own has no location to validate against, and would force a
// read of the stored row to resolve. Callers set the market as a pair, or send
// a location alone and let the service derive its language.
const hasLocationForLanguage = (input: {
locationCode?: number;
languageCode?: string;
}) => input.locationCode != null || input.languageCode == null;
const marketPairMessage = {
message: "A language requires a location.",
path: ["languageCode"],
};
export const createProjectSchema = z
.object({
name: projectNameField,
domain: projectDomainField,
locationCode: projectLocationCodeField,
languageCode: projectLanguageCodeField,
})
.refine(hasLocationForLanguage, marketPairMessage);
export const updateProjectSchema = z
.object({
projectId: z.string().min(1),
name: projectNameField,
domain: projectDomainField,
locationCode: projectLocationCodeField,
languageCode: projectLanguageCodeField,
})
.refine(hasLocationForLanguage, marketPairMessage);
// Market-only update (onboarding). Both halves are required: the caller picks
// them together, so the service can validate the pair without a stored row.
export const setProjectMarketSchema = z.object({
projectId: z.string().min(1),
name: projectNameField,
domain: projectDomainField,
locationCode: z
.number()
.int()
.refine(isSupportedLocationCode, "Unsupported DataForSEO location code"),
languageCode: z
.string()
.refine(isSupportedLanguageCode, "Unsupported language code"),
});
export const archiveProjectSchema = z.object({
@ -37,5 +89,6 @@ export const restoreProjectSchema = z.object({
export type CreateProjectInput = z.infer<typeof createProjectSchema>;
export type UpdateProjectInput = z.infer<typeof updateProjectSchema>;
export type SetProjectMarketInput = z.infer<typeof setProjectMarketSchema>;
export type ArchiveProjectInput = z.infer<typeof archiveProjectSchema>;
export type RestoreProjectInput = z.infer<typeof restoreProjectSchema>;