Skip to content

Open source alternative to Semrush and Ahrefs

Hide likely spam backlinks by default (EVE-265) (#667)

Carter Smith697d25be3b65
diff --git a/src/client/features/backlinks/BacklinksPage.tsx b/src/client/features/backlinks/BacklinksPage.tsx
index 53aa443a..b6177fb4 100644
--- a/src/client/features/backlinks/BacklinksPage.tsx
+++ b/src/client/features/backlinks/BacklinksPage.tsx
@@ -95,11 +95,6 @@ export function BacklinksPage({
[navigate],
);
- const domainExpansion = useBacklinksDomainExpansion({
- projectId,
- searchState,
- });
-
const {
activeTabErrorMessage,
activeTabQuery,
@@ -115,6 +110,12 @@ export function BacklinksPage({
filters,
});
+ const domainExpansion = useBacklinksDomainExpansion({
+ projectId,
+ searchState,
+ rows: activeTabErrorMessage ? [] : (rowsQuery.data?.rows ?? []),
+ });
+
const {
history,
isLoaded: historyLoaded,
@@ -224,6 +225,16 @@ export function BacklinksPage({
onSortingChange={handleSortingChange}
onTabChange={handleResultTabChange}
onViewChange={handleViewChange}
+ onHideSpamChange={(hideSpam) =>
+ navigate({
+ search: (prev) => ({
+ ...prev,
+ includeSpam: hideSpam ? undefined : true,
+ page: undefined,
+ }),
+ replace: true,
+ })
+ }
searchTabs={
searchState.target
? {
diff --git a/src/client/features/backlinks/BacklinksPageContent.tsx b/src/client/features/backlinks/BacklinksPageContent.tsx
index c451a810..cd4089c0 100644
--- a/src/client/features/backlinks/BacklinksPageContent.tsx
+++ b/src/client/features/backlinks/BacklinksPageContent.tsx
@@ -48,6 +48,7 @@ type BacklinksBodyProps = {
onSortingChange: OnChangeFn<SortingState>;
onTabChange: (tab: BacklinksSearchState["tab"]) => void;
onViewChange: (view: "all" | undefined) => void;
+ onHideSpamChange: (hideSpam: boolean) => void;
searchTabs: {
activeTabId: string | null;
tabs: SearchTab[];
@@ -81,6 +82,7 @@ export function BacklinksBody({
onSortingChange,
onTabChange,
onViewChange,
+ onHideSpamChange,
searchTabs,
}: BacklinksBodyProps) {
const tabRows = useMemo<BacklinksTabRows>(
@@ -147,6 +149,9 @@ export function BacklinksBody({
return (
<>
{tabStrip}
+ <p className="text-xs text-base-content/60">
+ Overview metrics cover the full target, before table filters.
+ </p>
<BacklinksOverviewPanels
projectId={projectId}
data={overviewData}
@@ -160,6 +165,8 @@ export function BacklinksBody({
filters={filters}
sorting={sorting}
view={searchState.view}
+ hideSpam={!searchState.includeSpam}
+ onHideSpamChange={onHideSpamChange}
domainExpansion={domainExpansion}
isTabLoading={tabLoading}
tabErrorMessage={tabErrorMessage}
diff --git a/src/client/features/backlinks/BacklinksPageSections.tsx b/src/client/features/backlinks/BacklinksPageSections.tsx
index 749a5c18..5ac67e37 100644
--- a/src/client/features/backlinks/BacklinksPageSections.tsx
+++ b/src/client/features/backlinks/BacklinksPageSections.tsx
@@ -1,7 +1,8 @@
import { useEffect, useMemo } from "react";
-import { SlidersHorizontal } from "lucide-react";
+import { Check, ChevronDown, Link2, SlidersHorizontal } from "lucide-react";
import type { OnChangeFn, SortingState } from "@tanstack/react-table";
import { BacklinksFilterPanel } from "./BacklinksFilterPanel";
+import { backlinksFilterConditionLimit } from "./backlinksFilterTypes";
import { BacklinksTable } from "./BacklinksTable";
import { ReferringDomainsTable } from "./ReferringDomainsTable";
import { TopPagesTable } from "./TopPagesTable";
@@ -21,13 +22,10 @@ import { useAhrefsDomainRatings } from "./useAhrefsDomainRatings";
import { TablePagination } from "@/client/components/table/TablePagination";
import {
BACKLINKS_PAGE_SIZES,
+ DEFAULT_BACKLINKS_SPAM_THRESHOLD,
type BacklinksTab,
} from "@/types/schemas/backlinks";
-import { MAX_DATAFORSEO_FILTER_CONDITIONS } from "@/types/schemas/domain";
-import {
- BACKLINKS_SUBFOLDER_FILTER_CONDITIONS,
- type ResearchScope,
-} from "@/shared/researchScope";
+import type { ResearchScope } from "@/shared/researchScope";
const BACKLINKS_RESULTS_TABS: Array<{
tab: BacklinksSearchState["tab"];
@@ -46,6 +44,8 @@ export function BacklinksResultsCard({
filters,
sorting,
view,
+ hideSpam,
+ onHideSpamChange,
domainExpansion,
isTabLoading,
tabErrorMessage,
@@ -64,6 +64,8 @@ export function BacklinksResultsCard({
filters: BacklinksFiltersState;
sorting: SortingState;
view: "all" | undefined;
+ hideSpam: boolean;
+ onHideSpamChange: (hideSpam: boolean) => void;
domainExpansion: BacklinksDomainExpansion;
isTabLoading: boolean;
tabErrorMessage: string | null;
@@ -110,7 +112,7 @@ export function BacklinksResultsCard({
}, [domainRatings, ratableDomains, loadRatings]);
return (
- <div className="border border-base-300 rounded-xl bg-base-100 overflow-hidden">
+ <div className="border border-base-300 rounded-xl bg-base-100">
<div className="flex flex-col lg:flex-row lg:items-center justify-between gap-3 px-4 py-3 border-b border-base-300">
<div className="space-y-2">
<div role="tablist" className="tabs tabs-border w-fit">
@@ -163,6 +165,51 @@ export function BacklinksResultsCard({
</span>
) : null}
</button>
+ {activeTab === "backlinks" ? (
+ <details className="dropdown">
+ <summary className="btn btn-ghost btn-sm gap-1.5">
+ <Link2 className="size-3.5" />
+ Best links: {hideSpam ? "On" : "Off"}
+ <ChevronDown className="size-3 opacity-60" />
+ </summary>
+ <ul
+ className="dropdown-content menu z-20 w-72 rounded-box border border-base-300 bg-base-100 p-2 shadow-lg"
+ onClick={(event) => {
+ const details = event.currentTarget.parentElement;
+ details?.removeAttribute("open");
+ details?.querySelector("summary")?.focus();
+ }}
+ >
+ <li>
+ <button type="button" onClick={() => onHideSpamChange(true)}>
+ <span className="w-4 shrink-0">
+ {hideSpam ? <Check className="size-4" /> : null}
+ </span>
+ <span>
+ <span className="block">Best links only</span>
+ <span className="block text-xs text-base-content/60">
+ Scores below {DEFAULT_BACKLINKS_SPAM_THRESHOLD} or unknown
+ </span>
+ </span>
+ </button>
+ </li>
+ <li>
+ <button type="button" onClick={() => onHideSpamChange(false)}>
+ <span className="w-4 shrink-0">
+ {!hideSpam ? <Check className="size-4" /> : null}
+ </span>
+ <span>
+ <span className="block">All links (spammy included)</span>
+ <span className="block text-xs text-base-content/60">
+ Includes scores {DEFAULT_BACKLINKS_SPAM_THRESHOLD} or
+ higher
+ </span>
+ </span>
+ </button>
+ </li>
+ </ul>
+ </details>
+ ) : null}
{activeTab === "backlinks" ? (
<div
role="tablist"
@@ -198,15 +245,11 @@ export function BacklinksResultsCard({
activeTab={activeTab}
filters={filters}
onApplied={() => onPageChange(1)}
- // The subfolder url-prefix group (and, on the backlinks tab, the
- // server-appended spam condition) shares the 8-condition budget.
- maxConditions={
- scope === "subfolder"
- ? MAX_DATAFORSEO_FILTER_CONDITIONS -
- BACKLINKS_SUBFOLDER_FILTER_CONDITIONS -
- (activeTab === "pages" ? 0 : 1)
- : undefined
- }
+ // Restored filters are also checked before the query can run.
+ maxConditions={backlinksFilterConditionLimit(
+ scope,
+ activeTab === "backlinks" && hideSpam,
+ )}
/>
) : null}
diff --git a/src/client/features/backlinks/BacklinksTable.test.ts b/src/client/features/backlinks/BacklinksTable.test.ts
new file mode 100644
index 00000000..c3369b21
--- /dev/null
+++ b/src/client/features/backlinks/BacklinksTable.test.ts
@@ -0,0 +1,30 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { load } from "cheerio";
+import { expect, it, vi } from "vitest";
+import { mapBacklinksRows } from "@/server/features/backlinks/services/backlinksRowMappers";
+import { BacklinksTable } from "./BacklinksTable";
+
+it("distinguishes zero from missing spam scores without changing boundary values", () => {
+ const rows = mapBacklinksRows(
+ [undefined, null, 0, 39, 40].map((score) => ({
+ url_from: "https://openseo.so/",
+ backlink_spam_score: score,
+ })),
+ );
+ const html = renderToStaticMarkup(
+ createElement(BacklinksTable, {
+ rows,
+ domainRatings: null,
+ sorting: [],
+ onSortingChange: vi.fn(),
+ expansion: null,
+ }),
+ );
+ const $ = load(html);
+ const scores = $("tbody tr")
+ .map((_, row) => $(row).find("td").eq(6).text())
+ .get();
+ expect(scores).toEqual(["—", "—", "0", "39", "40"]);
+ expect($("[title='Spam score unknown']")).toHaveLength(2);
+});
diff --git a/src/client/features/backlinks/BacklinksTableColumns.tsx b/src/client/features/backlinks/BacklinksTableColumns.tsx
index ac1df4d9..c276ddc0 100644
--- a/src/client/features/backlinks/BacklinksTableColumns.tsx
+++ b/src/client/features/backlinks/BacklinksTableColumns.tsx
@@ -254,7 +254,11 @@ function buildBaseColumns(
const value = row.spamScore;
return (
<div className="text-right tabular-nums text-sm">
- {value != null && value > 0 ? Math.round(value) : null}
+ {value != null ? (
+ Math.round(value)
+ ) : (
+ <span title="Spam score unknown">—</span>
+ )}
</div>
);
}),
diff --git a/src/client/features/backlinks/BacklinksToolbarMenus.tsx b/src/client/features/backlinks/BacklinksToolbarMenus.tsx
index 61647021..3306a5fc 100644
--- a/src/client/features/backlinks/BacklinksToolbarMenus.tsx
+++ b/src/client/features/backlinks/BacklinksToolbarMenus.tsx
@@ -56,6 +56,7 @@ export function BacklinksExportMenu({
role="menu"
className="dropdown-content z-10 menu p-2 shadow-lg bg-base-100 border border-base-300 rounded-box w-56"
>
+ <li className="menu-title text-xs">Current page · selected view</li>
<li>
<button
type="button"
diff --git a/src/client/features/backlinks/backlinksFilterTypes.test.ts b/src/client/features/backlinks/backlinksFilterTypes.test.ts
new file mode 100644
index 00000000..04948311
--- /dev/null
+++ b/src/client/features/backlinks/backlinksFilterTypes.test.ts
@@ -0,0 +1,26 @@
+import { expect, it } from "vitest";
+import {
+ backlinksFilterBudgetError,
+ EMPTY_BACKLINKS_FILTERS,
+} from "./backlinksFilterTypes";
+
+it("preserves seven saved conditions and offers recovery before a filtered request", () => {
+ const values = { ...EMPTY_BACKLINKS_FILTERS, exclude: "a,b,c,d,e,f,g" };
+ expect(backlinksFilterBudgetError(values, "subdomains", true)).toContain(
+ "choose All links (spammy included) from Best links",
+ );
+ expect(backlinksFilterBudgetError(values, "subdomains", false)).toBeNull();
+ expect(values.exclude).toBe("a,b,c,d,e,f,g");
+});
+
+it("accounts for subfolder conditions and accepts the exact remaining budget", () => {
+ const values = { ...EMPTY_BACKLINKS_FILTERS, exclude: "a,b" };
+ expect(backlinksFilterBudgetError(values, "subfolder", true)).toBeNull();
+ expect(
+ backlinksFilterBudgetError(
+ { ...values, exclude: "a,b,c" },
+ "subfolder",
+ true,
+ ),
+ ).toContain("2-condition limit");
+});
diff --git a/src/client/features/backlinks/backlinksFilterTypes.ts b/src/client/features/backlinks/backlinksFilterTypes.ts
index cf9fdb4d..48e62b86 100644
--- a/src/client/features/backlinks/backlinksFilterTypes.ts
+++ b/src/client/features/backlinks/backlinksFilterTypes.ts
@@ -114,6 +114,27 @@ export function countActiveFilters(values: Record<string, string>): number {
return Object.values(values).filter((v) => v.trim() !== "").length;
}
+export function backlinksFilterConditionLimit(
+ scope: ResearchScope,
+ hideSpam: boolean,
+): number {
+ return (
+ MAX_DATAFORSEO_FILTER_CONDITIONS -
+ (scope === "subfolder" ? BACKLINKS_SUBFOLDER_FILTER_CONDITIONS : 0) -
+ (hideSpam ? 2 : 0)
+ );
+}
+
+export function backlinksFilterBudgetError(
+ values: BacklinksTabFilterValues,
+ scope: ResearchScope,
+ hideSpam: boolean,
+): string | null {
+ const limit = backlinksFilterConditionLimit(scope, hideSpam);
+ if (countFilterConditions(values) <= limit) return null;
+ return `These filters exceed the ${limit}-condition limit for this view. Remove conditions in Filters${hideSpam ? " or choose All links (spammy included) from Best links" : ""}. Your filters have been kept.`;
+}
+
/**
* Mirrors how the server translates filters to DataForSEO conditions: each
* include/exclude term is one condition, every other non-empty field is one.
@@ -188,3 +209,8 @@ export function toTopPagesFiltersPayload(
maxRank: toNumberOrUndefined(values.maxRank),
};
}
+import { MAX_DATAFORSEO_FILTER_CONDITIONS } from "@/types/schemas/domain";
+import {
+ BACKLINKS_SUBFOLDER_FILTER_CONDITIONS,
+ type ResearchScope,
+} from "@/shared/researchScope";
diff --git a/src/client/features/backlinks/backlinksPageTypes.ts b/src/client/features/backlinks/backlinksPageTypes.ts
index 78606c8c..11dd39d7 100644
--- a/src/client/features/backlinks/backlinksPageTypes.ts
+++ b/src/client/features/backlinks/backlinksPageTypes.ts
@@ -28,6 +28,7 @@ export type ReferringDomainRow = BacklinksReferringDomainsData["rows"][number];
export type TopPageRow = BacklinksTopPagesData["rows"][number];
export type BacklinksSearchState = {
+ includeSpam?: boolean;
target: string;
scope: BacklinksTargetScope;
tab: BacklinksTab;
diff --git a/src/client/features/backlinks/useBacklinksDomainExpansion.ts b/src/client/features/backlinks/useBacklinksDomainExpansion.ts
index 42763e8d..d310b2a7 100644
--- a/src/client/features/backlinks/useBacklinksDomainExpansion.ts
+++ b/src/client/features/backlinks/useBacklinksDomainExpansion.ts
@@ -26,11 +26,13 @@ export type BacklinksDomainExpansion = {
export function useBacklinksDomainExpansion({
projectId,
searchState,
+ rows,
}: {
projectId: string;
searchState: BacklinksSearchState;
+ rows: BacklinksRow[];
}): BacklinksDomainExpansion {
- const { target, scope } = searchState;
+ const { target, scope, includeSpam } = searchState;
const [expanded, setExpanded] = useState<string[]>([]);
// Collapse everything when the lookup changes.
@@ -40,12 +42,17 @@ export function useBacklinksDomainExpansion({
const queries = useQueries({
queries: expanded.map((domain) => ({
+ enabled:
+ searchState.tab === "backlinks" &&
+ searchState.view !== "all" &&
+ rows.some((row) => row.domainFrom === domain),
queryKey: [
"backlinksDomainLinks",
projectId,
scope,
target,
domain,
+ includeSpam ?? false,
] as const,
staleTime: DOMAIN_LINKS_STALE_TIME_MS,
queryFn: () =>
@@ -60,6 +67,7 @@ export function useBacklinksDomainExpansion({
sortOrder: "desc",
filters: { domainFrom: domain },
mode: "as_is",
+ hideSpam: !includeSpam,
},
}),
})),
diff --git a/src/client/features/backlinks/useBacklinksPageData.ts b/src/client/features/backlinks/useBacklinksPageData.ts
index f0aa6ab3..a56a3e3b 100644
--- a/src/client/features/backlinks/useBacklinksPageData.ts
+++ b/src/client/features/backlinks/useBacklinksPageData.ts
@@ -23,6 +23,7 @@ import {
} from "@/types/schemas/backlinks";
import {
toBacklinksFiltersPayload,
+ backlinksFilterBudgetError,
toReferringDomainsFiltersPayload,
toTopPagesFiltersPayload,
} from "./backlinksFilterTypes";
@@ -105,6 +106,11 @@ export function useBacklinksPageData({
() => toBacklinksFiltersPayload(filters.backlinks.values),
[filters.backlinks.values],
);
+ const rowsFilterError = backlinksFilterBudgetError(
+ filters.backlinks.values,
+ scope,
+ !searchState.includeSpam,
+ );
const rowsQuery = useQuery({
queryKey: [
"backlinksRows",
@@ -115,8 +121,9 @@ export function useBacklinksPageData({
rowsSort.order,
rowsFilters,
rowsMode,
+ searchState.includeSpam ?? false,
],
- enabled: targetReady && tab === "backlinks",
+ enabled: targetReady && tab === "backlinks" && !rowsFilterError,
staleTime: BACKLINKS_QUERY_STALE_TIME_MS,
queryFn: () =>
getBacklinksRows({
@@ -126,6 +133,7 @@ export function useBacklinksPageData({
sortOrder: rowsSort.order,
filters: rowsFilters,
mode: rowsMode,
+ hideSpam: !searchState.includeSpam,
},
}),
});
@@ -206,10 +214,9 @@ export function useBacklinksPageData({
: tab === "domains"
? referringDomainsQuery
: topPagesQuery;
- const activeTabErrorMessage = getBacklinksErrorMessage(
- activeTabQuery.error,
- "Could not load this tab.",
- );
+ const activeTabErrorMessage =
+ (tab === "backlinks" ? rowsFilterError : null) ??
+ getBacklinksErrorMessage(activeTabQuery.error, "Could not load this tab.");
return {
activeTabErrorMessage,
diff --git a/src/routes/_project/p/$projectId/backlinks.tsx b/src/routes/_project/p/$projectId/backlinks.tsx
index 5317d3c5..9dc7541e 100644
--- a/src/routes/_project/p/$projectId/backlinks.tsx
+++ b/src/routes/_project/p/$projectId/backlinks.tsx
@@ -23,6 +23,7 @@ function BacklinksRoute() {
sort,
order,
view,
+ includeSpam,
} = Route.useSearch();
const scope = rawScope ?? defaultScopeForInput(target);
@@ -40,6 +41,7 @@ function BacklinksRoute() {
sort,
order,
view,
+ includeSpam,
}}
/>
);
diff --git a/src/server/features/backlinks/services/BacklinksService.billing.test.ts b/src/server/features/backlinks/services/BacklinksService.billing.test.ts
index e230798e..a235c32f 100644
--- a/src/server/features/backlinks/services/BacklinksService.billing.test.ts
+++ b/src/server/features/backlinks/services/BacklinksService.billing.test.ts
@@ -370,6 +370,7 @@ it("builds subfolder overview totals from two filtered backlink counts", async (
expect.objectContaining({
mode: "as_is",
limit: 1,
+ hideSpam: false,
filters: [
[
["url_to", "like", "%://example.com/blog"],
@@ -385,6 +386,10 @@ it("builds subfolder overview totals from two filtered backlink counts", async (
);
expect(backlinksRowsMock).toHaveBeenNthCalledWith(
2,
- expect.objectContaining({ mode: "one_per_domain", limit: 1 }),
+ expect.objectContaining({
+ mode: "one_per_domain",
+ limit: 1,
+ hideSpam: false,
+ }),
);
});
diff --git a/src/server/features/backlinks/services/BacklinksService.ts b/src/server/features/backlinks/services/BacklinksService.ts
index f724871b..65396ce8 100644
--- a/src/server/features/backlinks/services/BacklinksService.ts
+++ b/src/server/features/backlinks/services/BacklinksService.ts
@@ -1,9 +1,8 @@
import { buildCacheKey, getCached, setCached } from "@/server/lib/r2-cache";
import { normalizeBacklinksTarget } from "@/server/lib/dataforseo";
-import {
- normalizeBacklinksSpamFilterOptions,
- type BacklinksLookupInput,
- type BacklinksSpamFilterOptions,
+import type {
+ BacklinksLookupInput,
+ BacklinksSpamFilterOptions,
} from "@/types/schemas/backlinks";
import {
profileBacklinksOverview,
@@ -45,7 +44,7 @@ function createBacklinksService(cache: BacklinksCache = defaultCache) {
// results stay shared across callers.
creditFeature?: CreditFeature,
) {
- const cacheKey = await buildCacheKey("backlinks:overview", {
+ const cacheKey = await buildCacheKey("backlinks:overview:v2", {
...buildTargetCacheInput(input, billingCustomer),
});
@@ -63,7 +62,7 @@ function createBacklinksService(cache: BacklinksCache = defaultCache) {
options?: BacklinksSpamFilterOptions,
) {
const cacheKey = await buildPageCacheKey(
- "backlinks:rows-page",
+ "backlinks:rows-page:v2",
input,
billingCustomer,
options,
@@ -139,8 +138,6 @@ async function buildPageCacheKey(
billingCustomer: BillingCustomerContext,
options?: BacklinksSpamFilterOptions,
): Promise<string> {
- const spamFilterOptions = normalizeBacklinksSpamFilterOptions(options);
-
return buildCacheKey(prefix, {
...buildTargetCacheInput(input, billingCustomer),
page: input.page,
@@ -149,10 +146,7 @@ async function buildPageCacheKey(
sortOrder: input.sortOrder,
filters: input.filters,
...(input.mode ? { mode: input.mode } : {}),
- hideSpam: String(spamFilterOptions.hideSpam),
- ...(spamFilterOptions.hideSpam
- ? { spamThreshold: String(spamFilterOptions.spamThreshold) }
- : {}),
+ hideSpam: String(options?.hideSpam ?? true),
});
}
diff --git a/src/server/features/backlinks/services/backlinksServiceData.ts b/src/server/features/backlinks/services/backlinksServiceData.ts
index 5a37b8d3..5f248430 100644
--- a/src/server/features/backlinks/services/backlinksServiceData.ts
+++ b/src/server/features/backlinks/services/backlinksServiceData.ts
@@ -7,13 +7,12 @@ import {
type BacklinksHistoryItem,
type BacklinksSummaryItem,
} from "@/server/lib/dataforseo";
-import {
- normalizeBacklinksSpamFilterOptions,
- type BacklinksLookupInput,
- type BacklinksRowsPageInput,
- type BacklinksSpamFilterOptions,
- type ReferringDomainsPageInput,
- type TopPagesPageInput,
+import type {
+ BacklinksLookupInput,
+ BacklinksRowsPageInput,
+ BacklinksSpamFilterOptions,
+ ReferringDomainsPageInput,
+ TopPagesPageInput,
} from "@/types/schemas/backlinks";
import {
@@ -178,7 +177,7 @@ export async function profileBacklinksRowsPage(
assertFilterConditionBudget(
scopeFilter.conditionCount +
countExpressionConditions(userFilters) +
- (normalizeBacklinksSpamFilterOptions(spamOptions).hideSpam ? 1 : 0),
+ ((spamOptions?.hideSpam ?? true) ? 2 : 0),
);
const filters = prependScopeClauses(scopeFilter, userFilters);
diff --git a/src/server/features/backlinks/services/backlinksSubfolderOverview.ts b/src/server/features/backlinks/services/backlinksSubfolderOverview.ts
index de2e88b7..9b78cd8e 100644
--- a/src/server/features/backlinks/services/backlinksSubfolderOverview.ts
+++ b/src/server/features/backlinks/services/backlinksSubfolderOverview.ts
@@ -26,6 +26,7 @@ export async function buildSubfolderOverview(
includeSubdomains: normalizedTarget.includeSubdomains,
limit: 1,
mode: "as_is",
+ hideSpam: false,
filters,
creditFeature,
});
@@ -34,6 +35,7 @@ export async function buildSubfolderOverview(
includeSubdomains: normalizedTarget.includeSubdomains,
limit: 1,
mode: "one_per_domain",
+ hideSpam: false,
filters,
creditFeature,
});
diff --git a/src/server/lib/dataforseo/backlinks.test.ts b/src/server/lib/dataforseo/backlinks.test.ts
index 49df5add..86961f3b 100644
--- a/src/server/lib/dataforseo/backlinks.test.ts
+++ b/src/server/lib/dataforseo/backlinks.test.ts
@@ -228,6 +228,52 @@ describe("fetchBacklinksSummary", () => {
}),
).resolves.toMatchObject({ data: [] });
});
+
+ it.each([
+ ["as_is", undefined],
+ ["one_per_domain", undefined],
+ ["as_is", false],
+ ["one_per_domain", false],
+ ] as const)(
+ "preserves user filters and pagination for %s with hideSpam=%s",
+ async (mode, hideSpam) => {
+ vi.mocked(fetch).mockResolvedValue(okResponse([]));
+ classifyBacklinksError.mockReturnValue(null);
+ const filters = [["domain_from", "=", "openseo.so"]];
+
+ await fetchBacklinksRows({
+ target: "openseo.so",
+ mode,
+ offset: 50,
+ limit: 50,
+ hideSpam,
+ filters,
+ });
+
+ const body = vi.mocked(fetch).mock.calls[0]?.[1]?.body;
+ if (typeof body !== "string")
+ throw new Error("Expected a JSON request body");
+ expect(JSON.parse(body)).toEqual([
+ expect.objectContaining({
+ mode,
+ offset: 50,
+ limit: 50,
+ filters:
+ hideSpam === false
+ ? filters
+ : [
+ ...filters,
+ "and",
+ [
+ ["backlink_spam_score", "<", 40],
+ "or",
+ ["backlink_spam_score", "=", null],
+ ],
+ ],
+ }),
+ ]);
+ },
+ );
});
function expectValidationError(fn: () => unknown) {
diff --git a/src/server/lib/dataforseo/backlinks.ts b/src/server/lib/dataforseo/backlinks.ts
index a8001e7c..f20b16ee 100644
--- a/src/server/lib/dataforseo/backlinks.ts
+++ b/src/server/lib/dataforseo/backlinks.ts
@@ -1,6 +1,6 @@
import { z } from "zod";
import {
- normalizeBacklinksSpamFilterOptions,
+ DEFAULT_BACKLINKS_SPAM_THRESHOLD,
type BacklinksSpamFilterOptions,
} from "@/types/schemas/backlinks";
import { createDataforseoBillingClassifier } from "@/server/lib/dataforseoBillingClassification";
@@ -204,11 +204,14 @@ export async function fetchBacklinksSummary(input: BacklinksRequest) {
}
export async function fetchBacklinksRows(input: BacklinksListRequest) {
- const spamFilterOptions = normalizeBacklinksSpamFilterOptions(input);
const filters = combineFilters(
input.filters,
- spamFilterOptions.hideSpam
- ? ["backlink_spam_score", "<=", spamFilterOptions.spamThreshold]
+ (input.hideSpam ?? true)
+ ? [
+ ["backlink_spam_score", "<", DEFAULT_BACKLINKS_SPAM_THRESHOLD],
+ "or",
+ ["backlink_spam_score", "=", null],
+ ]
: undefined,
);
const response = await dataforseoPost(
@@ -239,11 +242,10 @@ export async function fetchBacklinksRows(input: BacklinksListRequest) {
}
export async function fetchReferringDomains(input: BacklinksListRequest) {
- const spamFilterOptions = normalizeBacklinksSpamFilterOptions(input);
const filters = combineFilters(
input.filters,
- spamFilterOptions.hideSpam
- ? ["backlinks_spam_score", "<=", spamFilterOptions.spamThreshold]
+ (input.hideSpam ?? true)
+ ? ["backlinks_spam_score", "<=", DEFAULT_BACKLINKS_SPAM_THRESHOLD]
: undefined,
);
const response = await dataforseoPost(
diff --git a/src/server/mcp/tools/get-backlinks-profile.ts b/src/server/mcp/tools/get-backlinks-profile.ts
index bdaaff5d..17a4bb44 100644
--- a/src/server/mcp/tools/get-backlinks-profile.ts
+++ b/src/server/mcp/tools/get-backlinks-profile.ts
@@ -69,7 +69,9 @@ const inputSchema = {
hideSpam: z
.boolean()
.optional()
- .describe("Filter out spammy backlinks. Defaults to true."),
+ .describe(
+ "Hide backlinks with Spam scores of 40 or higher. Defaults to true. Unknown scores remain visible. This is a heuristic, not a judgment about a link. Set false to inspect all matching links. True leaves six user filter conditions (two for subfolders); false allows eight (four for subfolders). Each include/exclude term and numeric bound counts separately.",
+ ),
} as const;
type Args = z.infer<z.ZodObject<typeof inputSchema>>;
diff --git a/src/serverFunctions/backlinks.ts b/src/serverFunctions/backlinks.ts
index 68ff1607..6a1532ce 100644
--- a/src/serverFunctions/backlinks.ts
+++ b/src/serverFunctions/backlinks.ts
@@ -8,8 +8,7 @@ import {
topPagesPageRequestSchema,
} from "@/types/schemas/backlinks";
-// The web UI exposes spam score as a regular user filter, so the implicit
-// DataForSEO spam-score cutoff stays off for all web requests.
+// Referring-domain scores aggregate multiple links and retain their own filters.
const WEB_SPAM_OPTIONS = { hideSpam: false };
export const getBacklinksOverview = createServerFn({
@@ -34,7 +33,9 @@ export const getBacklinksRows = createServerFn({
.middleware(requireProjectContext)
.validator(backlinksRowsPageRequestSchema)
.handler(({ data, context }) =>
- BacklinksService.profileBacklinksPage(data, context, WEB_SPAM_OPTIONS),
+ BacklinksService.profileBacklinksPage(data, context, {
+ hideSpam: data.hideSpam ?? true,
+ }),
);
export const getBacklinksReferringDomains = createServerFn({
diff --git a/src/types/schemas/backlinks.ts b/src/types/schemas/backlinks.ts
index 820834fc..643c33c2 100644
--- a/src/types/schemas/backlinks.ts
+++ b/src/types/schemas/backlinks.ts
@@ -40,35 +40,12 @@ export const backlinksScopeParamSchema =
/** Shared wording for the MCP tools that take a backlinks scope. */
export const BACKLINKS_SCOPE_DESCRIPTION = `${RESEARCH_SCOPE_PARAM_DESCRIPTION} 'page' is a deprecated alias of 'exact_url'. Subfolder counts are computed from filtered backlink totals; rank, trends, and the referring-domains breakdown are unavailable for subfolders.`;
-const DEFAULT_BACKLINKS_SPAM_THRESHOLD = 40;
-
-function normalizeBacklinksSpamThreshold(value: number) {
- if (!Number.isFinite(value)) {
- return DEFAULT_BACKLINKS_SPAM_THRESHOLD;
- }
-
- return Math.min(100, Math.max(0, Math.trunc(value)));
-}
+export const DEFAULT_BACKLINKS_SPAM_THRESHOLD = 40;
export type BacklinksSpamFilterOptions = {
hideSpam?: boolean;
- spamThreshold?: number;
};
-export function normalizeBacklinksSpamFilterOptions(
- options?: BacklinksSpamFilterOptions,
-) {
- const hideSpam = options?.hideSpam ?? true;
-
- return {
- hideSpam,
- spamThreshold: hideSpam
- ? normalizeBacklinksSpamThreshold(
- options?.spamThreshold ?? DEFAULT_BACKLINKS_SPAM_THRESHOLD,
- )
- : undefined,
- };
-}
export const backlinksLookupSchema = z.object({
target: z.string().min(1, "Target is required").max(2048),
scope: backlinksScopeParamSchema.optional(),
@@ -196,6 +173,7 @@ const backlinksPageRequestBase = backlinksLookupSchema.extend({
});
export const backlinksRowsPageRequestSchema = backlinksPageRequestBase.extend({
+ hideSpam: z.boolean().optional(),
sortField: backlinksRowsSortFieldSchema.default(
BACKLINKS_DEFAULT_SORT.backlinks.field,
),
@@ -219,6 +197,7 @@ export const topPagesPageRequestSchema = backlinksPageRequestBase.extend({
});
export const backlinksSearchSchema = z.object({
+ includeSpam: z.boolean().optional().catch(undefined),
target: z.string().optional(),
scope: backlinksScopeParamSchema.optional().catch(undefined),
tab: backlinksTabSchema.optional(),