@@ -39,332 +50,286 @@ function BacklinkFlags({ row }: { row: BacklinksRow }) {
);
}
-function DomainFlagBadges({ group }: { group: GroupedBacklinkDomain }) {
- const badges: Array<{ label: string; className: string }> = [];
- if (group.lostCount > 0) {
- badges.push({
- label: `${group.lostCount} Lost`,
- className:
- "badge badge-sm badge-error badge-outline min-w-fit whitespace-nowrap",
- });
+function StatusCell({ status }: { status: "loading" | "error" | "empty" }) {
+ if (status === "loading") {
+ return (
+
+
+ Loading links…
+
+ );
}
- if (group.brokenCount > 0) {
- badges.push({
- label: `${group.brokenCount} Broken`,
- className:
- "badge badge-sm badge-warning badge-outline min-w-fit whitespace-nowrap",
- });
- }
- if (group.nofollowCount > 0) {
- badges.push({
- label: `${group.nofollowCount} Nofollow`,
- className: "badge badge-sm badge-outline min-w-fit whitespace-nowrap",
- });
- }
- if (badges.length === 0) return null;
-
return (
-
- {badges.map((badge) => (
-
- {badge.label}
-
- ))}
+
+ {status === "error"
+ ? "Couldn't load this domain's links."
+ : "No other links from this domain."}
+
+ );
+}
+
+function SourceCell({
+ displayRow,
+ onToggleDomain,
+}: {
+ displayRow: BacklinksDisplayRow;
+ onToggleDomain?: (domain: string) => void;
+}) {
+ if (displayRow.kind === "status") {
+ return
;
+ }
+
+ const { row, depth, expandable, expanded } = displayRow;
+ if (depth > 0) {
+ return (
+
+ {row.urlFrom ? (
+
+ ) : (
+ -
+ )}
+
+ );
+ }
+
+ const domainLabel = row.domainFrom?.replace(/^www\./, "") ?? "-";
+ return (
+
+ {expandable && row.domainFrom && onToggleDomain ? (
+
+ ) : null}
+
+
{domainLabel}
+ {row.urlFrom ? (
+
+ ) : null}
+
);
}
-const baseBacklinksColumns: ColumnDef
[] = [
- {
- id: "source",
- accessorKey: "domain",
- header: ({ column }) => (
-
- ),
- size: 250,
- minSize: 180,
- cell: ({ row }) => {
- if (row.depth > 0) {
- const child = row.original._backlink;
- return (
-
- {child?.urlFrom ? (
-
- ) : (
- -
- )}
-
- );
- }
+/** Renders nothing for status rows, the link cell otherwise. */
+function linkCell(
+ render: (row: BacklinksRow) => React.ReactNode,
+): (ctx: { row: { original: BacklinksDisplayRow } }) => React.ReactNode {
+ return ({ row }) =>
+ row.original.kind === "link" ? render(row.original.row) : null;
+}
- const group = row.original;
- return (
-
-
-
-
{group.domain}
-
- {group.backlinkCount}{" "}
- {group.backlinkCount === 1 ? "backlink" : "backlinks"} ·{" "}
- {group.targetCount} {group.targetCount === 1 ? "page" : "pages"}
-
-
+function buildBaseColumns(
+ onToggleDomain?: (domain: string) => void,
+): ColumnDef
[] {
+ // Sortable column ids ("rank", "domainRank", "spamScore", "firstSeen") map
+ // to server-side sort fields — sorting re-queries DataForSEO across the
+ // full backlink profile, not just the loaded page.
+ return [
+ {
+ id: "source",
+ enableSorting: false,
+ header: () => (
+
+ ),
+ size: 250,
+ minSize: 180,
+ cell: ({ row }) => (
+
+ ),
+ },
+ {
+ id: "target",
+ enableSorting: false,
+ header: () => (
+
+ ),
+ size: 220,
+ minSize: 150,
+ cell: linkCell((row) => (
+
+ {row.urlTo ? (
+
+ ) : (
+ "-"
+ )}
- );
+ )),
},
- sortingFn: stringNullsLast,
- },
- {
- id: "target",
- header: () => (
-
- ),
- size: 220,
- minSize: 150,
- enableSorting: false,
- cell: ({ row }) => {
- if (row.depth > 0) {
- const child = row.original._backlink;
- return (
-
- {child?.urlTo ? (
-
- ) : (
- "-"
- )}
-
- );
- }
-
- return null;
+ {
+ id: "anchor",
+ enableSorting: false,
+ header: () => (
+
+ ),
+ size: 150,
+ minSize: 100,
+ cell: linkCell((row) => (
+
+
{row.anchor || "No anchor text"}
+ {row.itemType ? (
+
{row.itemType}
+ ) : null}
+
-
{child?.anchor || "No anchor text"}
- {child?.itemType ? (
-
- {child.itemType}
-
- ) : null}
-
+ {formatNumber(row.rank)}
+
+ )),
+ },
+ {
+ id: "domainRank" satisfies BacklinksRowsSortField,
+ accessorFn: (displayRow) =>
+ displayRow.kind === "link" ? displayRow.row.domainFromRank : null,
+ header: ({ column }) => (
+
+ ),
+ size: 70,
+ minSize: 50,
+ sortDescFirst: true,
+ cell: linkCell((row) => (
+
+ {formatNumber(row.domainFromRank)}
+
+ )),
+ },
+ {
+ id: "spamScore" satisfies BacklinksRowsSortField,
+ accessorFn: (displayRow) =>
+ displayRow.kind === "link" ? displayRow.row.spamScore : null,
+ header: ({ column }) => (
+
+ ),
+ size: 70,
+ minSize: 50,
+ sortDescFirst: true,
+ cell: linkCell((row) => {
+ const value = row.spamScore;
return (
-
- {formatNumber(child?.rank)}
-
+ {value != null && value > 0 ? Math.round(value) : null}
);
- }
-
- return null;
+ }),
},
- },
- {
- id: "domainAuthority",
- accessorKey: "domainAuthority",
- header: ({ column }) => (
-
- ),
- size: 70,
- minSize: 50,
- cell: ({ row }) => {
- if (row.depth > 0) return null;
-
- return (
-
- {formatNumber(row.original.domainAuthority)}
-
- );
- },
- sortingFn: numericNullsLast,
- sortDescFirst: true,
- },
- {
- id: "spamScore",
- accessorKey: "spamScore",
- header: ({ column }) => (
-
- ),
- size: 70,
- minSize: 50,
- cell: ({ row }) => {
- const value =
- row.depth > 0
- ? row.original._backlink?.spamScore
- : row.original.spamScore;
-
- return (
-
- {value != null && value > 0 ? Math.round(value) : null}
-
- );
- },
- sortingFn: numericNullsLast,
- sortDescFirst: true,
- },
- {
- id: "firstSeen",
- accessorKey: "firstSeen",
- header: ({ column }) => (
-
- ),
- size: 110,
- minSize: 80,
- cell: ({ row }) => {
- if (row.depth > 0) {
- const child = row.original._backlink;
- return (
-
-
{formatCompactDate(child?.firstSeen)}
- {child?.lastSeen ? (
-
- Last {formatCompactDate(child.lastSeen)}
-
- ) : null}
-
- {formatCompactDate(row.original.firstSeen)}
+
{formatCompactDate(row.firstSeen)}
+ {row.lastSeen ? (
+
+ Last {formatCompactDate(row.lastSeen)}
+
+ ) : null}
{dr == null ? "—" : formatDecimal(dr)}
);
- },
- sortingFn: numericNullsLast,
- sortDescFirst: true,
+ }),
};
const insertAt =
- baseBacklinksColumns.findIndex(
- (column) => column.id === "domainAuthority",
- ) + 1;
+ baseColumns.findIndex((column) => column.id === "domainRank") + 1;
return [
- ...baseBacklinksColumns.slice(0, insertAt),
+ ...baseColumns.slice(0, insertAt),
drColumn,
- ...baseBacklinksColumns.slice(insertAt),
+ ...baseColumns.slice(insertAt),
];
}
diff --git a/src/client/features/backlinks/BacklinksToolbarMenus.tsx b/src/client/features/backlinks/BacklinksToolbarMenus.tsx
index e63f9b0..6164702 100644
--- a/src/client/features/backlinks/BacklinksToolbarMenus.tsx
+++ b/src/client/features/backlinks/BacklinksToolbarMenus.tsx
@@ -8,26 +8,17 @@ import {
} from "lucide-react";
import type { CsvValue } from "@/client/lib/csv";
import { exportTableToSheets } from "@/client/lib/exportToSheets";
-import type {
- BacklinksOverviewData,
- BacklinksSearchState,
-} from "./backlinksPageTypes";
+import type { BacklinksSearchState } from "./backlinksPageTypes";
import { exportBacklinksTabCsv } from "./export";
export function BacklinksExportMenu({
activeTab,
exportTarget,
- filteredData,
headers,
rows,
}: {
activeTab: BacklinksSearchState["tab"];
exportTarget: string;
- filteredData: {
- backlinks: BacklinksOverviewData["backlinks"];
- referringDomains: BacklinksOverviewData["referringDomains"];
- topPages: BacklinksOverviewData["topPages"];
- };
headers: string[];
rows: CsvValue[][];
}) {
@@ -86,7 +77,8 @@ export function BacklinksExportMenu({
exportBacklinksTabCsv({
tab: activeTab,
target: exportTarget,
- rows: filteredData,
+ headers,
+ rows,
})
}
disabled={rows.length === 0}
diff --git a/src/client/features/backlinks/ReferringDomainsTable.tsx b/src/client/features/backlinks/ReferringDomainsTable.tsx
index 11c2777..a7a8df5 100644
--- a/src/client/features/backlinks/ReferringDomainsTable.tsx
+++ b/src/client/features/backlinks/ReferringDomainsTable.tsx
@@ -1,24 +1,16 @@
-import {
- createColumnHelper,
- type SortingFn,
- type SortingState,
-} from "@tanstack/react-table";
-import { useMemo, useState } from "react";
+import { createColumnHelper } from "@tanstack/react-table";
+import type { OnChangeFn, SortingState } from "@tanstack/react-table";
+import { useMemo } from "react";
import { SafeExternalLink } from "@/client/components/SafeExternalLink";
import {
AppDataTable,
useAppTable,
} from "@/client/components/table/AppDataTable";
import { SortableHeader } from "@/client/components/table/SortableHeader";
-import {
- compareNumericNullsLast,
- dateNullsLast,
- isDescending,
- numericNullsLast,
- stringNullsLast,
-} from "@/client/components/table/nullSafeSort";
+import { HeaderHelpLabel } from "@/client/features/keywords/components";
import { EmptyTableState } from "./BacklinksPageEmptyTableState";
-import type { BacklinksOverviewData } from "./backlinksPageTypes";
+import type { ReferringDomainRow } from "./backlinksPageTypes";
+import type { ReferringDomainsSortField } from "@/types/schemas/backlinks";
import {
formatCompactDate,
formatDecimal,
@@ -26,30 +18,13 @@ import {
} from "./backlinksPageUtils";
import type { DomainRatings } from "./useAhrefsDomainRatings";
-type ReferringDomainRow = BacklinksOverviewData["referringDomains"][number];
-
const columnHelper = createColumnHelper();
-// Nulls always to the bottom in both directions, same as the pre-TanStack
-// implementation. Secondary compare on brokenPages must also keep nulls last —
-// coercing to 0 would mix unknown values with real zeroes.
-const sortByIssues: SortingFn = (left, right, columnId) => {
- const descending = isDescending(left, columnId);
- const primary = compareNumericNullsLast(
- left.original.brokenBacklinks,
- right.original.brokenBacklinks,
- descending,
- );
- if (primary !== 0) return primary;
- return compareNumericNullsLast(
- left.original.brokenPages,
- right.original.brokenPages,
- descending,
- );
-};
-
+// Column ids map to server-side sort fields; sorting re-queries DataForSEO
+// across all referring domains, not just the loaded page.
const baseColumns = [
columnHelper.accessor("domain", {
+ id: "domain" satisfies ReferringDomainsSortField,
header: ({ column }) => (
);
},
- sortingFn: stringNullsLast,
}),
columnHelper.accessor("backlinks", {
+ id: "backlinks" satisfies ReferringDomainsSortField,
header: ({ column }) => (
),
cell: ({ getValue }) => formatNumber(getValue()),
- sortingFn: numericNullsLast,
sortDescFirst: true,
}),
columnHelper.accessor("referringPages", {
+ id: "referringPages" satisfies ReferringDomainsSortField,
header: ({ column }) => (
),
cell: ({ getValue }) => formatNumber(getValue()),
- sortingFn: numericNullsLast,
sortDescFirst: true,
}),
columnHelper.accessor("rank", {
+ id: "rank" satisfies ReferringDomainsSortField,
header: ({ column }) => (
),
cell: ({ getValue }) => formatNumber(getValue()),
- sortingFn: numericNullsLast,
sortDescFirst: true,
}),
columnHelper.accessor("spamScore", {
+ id: "spamScore" satisfies ReferringDomainsSortField,
header: ({ column }) => (
),
cell: ({ getValue }) => formatDecimal(getValue()),
- sortingFn: numericNullsLast,
sortDescFirst: true,
}),
columnHelper.accessor("firstSeen", {
+ id: "firstSeen" satisfies ReferringDomainsSortField,
header: ({ column }) => (
),
cell: ({ getValue }) => formatCompactDate(getValue()),
- sortingFn: dateNullsLast,
sortDescFirst: true,
}),
- columnHelper.display({
- id: "issues",
+ columnHelper.accessor("brokenBacklinks", {
+ id: "brokenBacklinks" satisfies ReferringDomainsSortField,
header: ({ column }) => (
+ {renderExtra ? renderExtra(draftFilters, handleValueChange) : null}
+
{meta.overLimit ? (
diff --git a/src/routes/_project/p/$projectId/backlinks.tsx b/src/routes/_project/p/$projectId/backlinks.tsx
index 3bceb25..7581577 100644
--- a/src/routes/_project/p/$projectId/backlinks.tsx
+++ b/src/routes/_project/p/$projectId/backlinks.tsx
@@ -1,7 +1,10 @@
import { createFileRoute, useNavigate } from "@tanstack/react-router";
import { BacklinksPage } from "@/client/features/backlinks/BacklinksPage";
import { inferBacklinksSearchScopeFromTarget } from "@/client/features/backlinks/backlinksSearchScope";
-import { backlinksSearchSchema } from "@/types/schemas/backlinks";
+import {
+ DEFAULT_BACKLINKS_PAGE_SIZE,
+ backlinksSearchSchema,
+} from "@/types/schemas/backlinks";
export const Route = createFileRoute("/_project/p/$projectId/backlinks")({
validateSearch: backlinksSearchSchema,
@@ -11,7 +14,16 @@ export const Route = createFileRoute("/_project/p/$projectId/backlinks")({
function BacklinksRoute() {
const { projectId } = Route.useParams();
const navigate = useNavigate({ from: Route.fullPath });
- const { target = "", scope: rawScope, tab = "backlinks" } = Route.useSearch();
+ const {
+ target = "",
+ scope: rawScope,
+ tab = "backlinks",
+ page = 1,
+ size = DEFAULT_BACKLINKS_PAGE_SIZE,
+ sort,
+ order,
+ view,
+ } = Route.useSearch();
const scope = rawScope ?? inferBacklinksSearchScopeFromTarget(target);
return (
@@ -22,6 +34,11 @@ function BacklinksRoute() {
target,
scope,
tab,
+ page,
+ pageSize: size,
+ sort,
+ order,
+ view,
}}
/>
);
diff --git a/src/server/features/backlinks/services/BacklinksService.billing.test.ts b/src/server/features/backlinks/services/BacklinksService.billing.test.ts
index 0d87779..3bf8518 100644
--- a/src/server/features/backlinks/services/BacklinksService.billing.test.ts
+++ b/src/server/features/backlinks/services/BacklinksService.billing.test.ts
@@ -37,6 +37,15 @@ const billingCustomer = {
userEmail: "team@example.com",
};
+const pageInputDefaults = {
+ projectId: "project_123",
+ page: 1,
+ pageSize: 100,
+ sortOrder: "desc",
+ filters: {},
+ mode: "as_is",
+} as const;
+
const cache = new Map
();
const service = createBacklinksService({
async get(key) {
@@ -53,7 +62,7 @@ beforeEach(() => {
vi.clearAllMocks();
});
-it("profiles only the initial overview calls and reuses cache on repeat", async () => {
+it("profiles only the summary and history for the overview and reuses cache on repeat", async () => {
vi.mocked(normalizeBacklinksTarget).mockReturnValue({
apiTarget: "example.com",
displayTarget: "example.com",
@@ -73,27 +82,6 @@ it("profiles only the initial overview calls and reuses cache on repeat", async
new_referring_domains: 8,
lost_referring_domains: 2,
});
- backlinksRowsMock.mockResolvedValue([
- {
- domain_from: "source.example",
- url_from: "https://source.example/post",
- url_to: "https://example.com/",
- anchor: "Example",
- item_type: "content",
- dofollow: true,
- rank: 77,
- domain_from_rank: 65,
- page_from_rank: 54,
- backlink_spam_score: 3,
- first_seen: "2026-01-01",
- last_visited: "2026-03-01",
- lost_date: null,
- is_lost: false,
- is_broken: false,
- links_count: 1,
- rel_attributes: ["noopener"],
- },
- ]);
backlinksHistoryMock.mockResolvedValue([
{
date: "2026-02-01",
@@ -116,8 +104,9 @@ it("profiles only the initial overview calls and reuses cache on repeat", async
billingCustomer,
);
- expect(first.overview.referringDomains).toEqual([]);
- expect(first.overview.topPages).toEqual([]);
+ expect(first.overview.summary.backlinks).toBe(1200);
+ expect(first.overview.trends).toHaveLength(1);
+ expect(backlinksRowsMock).not.toHaveBeenCalled();
expect(referringDomainsMock).not.toHaveBeenCalled();
expect(domainPagesMock).not.toHaveBeenCalled();
expect(backlinksSummaryMock).toHaveBeenCalledOnce();
@@ -125,46 +114,157 @@ it("profiles only the initial overview calls and reuses cache on repeat", async
expect(second).toEqual(first);
});
-it("profiles referring domains and top pages separately", async () => {
+it("profiles backlink rows per page with offset and total count", async () => {
+ vi.mocked(normalizeBacklinksTarget).mockReturnValue({
+ apiTarget: "example.com",
+ displayTarget: "example.com",
+ scope: "domain",
+ });
+ backlinksRowsMock.mockResolvedValue({
+ items: [
+ {
+ domain_from: "source.example",
+ url_from: "https://source.example/post",
+ url_to: "https://example.com/",
+ anchor: "Example",
+ item_type: "content",
+ dofollow: true,
+ rank: 77,
+ domain_from_rank: 65,
+ page_from_rank: 54,
+ backlink_spam_score: 3,
+ first_seen: "2026-01-01",
+ last_visited: "2026-03-01",
+ lost_date: null,
+ is_lost: false,
+ is_broken: false,
+ links_count: 1,
+ rel_attributes: ["noopener"],
+ },
+ ],
+ totalCount: 450,
+ });
+
+ const result = await service.profileBacklinksPage(
+ {
+ ...pageInputDefaults,
+ target: "example.com",
+ page: 2,
+ sortField: "rank",
+ },
+ billingCustomer,
+ { hideSpam: false },
+ );
+
+ expect(backlinksRowsMock).toHaveBeenCalledWith(
+ expect.objectContaining({
+ target: "example.com",
+ limit: 100,
+ offset: 100,
+ orderBy: ["rank,desc"],
+ hideSpam: false,
+ }),
+ );
+ expect(result.rows).toHaveLength(1);
+ expect(result.totalCount).toBe(450);
+ expect(result.hasMore).toBe(true);
+ expect(result.page).toBe(2);
+});
+
+it("translates filters into DataForSEO conditions for backlink rows", async () => {
+ vi.mocked(normalizeBacklinksTarget).mockReturnValue({
+ apiTarget: "example.com",
+ displayTarget: "example.com",
+ scope: "domain",
+ });
+ backlinksRowsMock.mockResolvedValue({ items: [], totalCount: 0 });
+
+ await service.profileBacklinksPage(
+ {
+ ...pageInputDefaults,
+ target: "example.com",
+ sortField: "rank",
+ filters: {
+ include: "blog",
+ minDomainRank: 30,
+ linkType: "dofollow",
+ hideLost: true,
+ },
+ },
+ billingCustomer,
+ { hideSpam: false },
+ );
+
+ expect(backlinksRowsMock).toHaveBeenCalledWith(
+ expect.objectContaining({
+ filters: [
+ ["url_from", "ilike", "%blog%"],
+ "and",
+ ["domain_from_rank", ">=", 30],
+ "and",
+ ["dofollow", "=", true],
+ "and",
+ ["is_lost", "=", false],
+ ],
+ }),
+ );
+});
+
+it("profiles referring domains and top pages pages separately", async () => {
vi.mocked(normalizeBacklinksTarget).mockReturnValue({
apiTarget: "https://example.com/foo",
displayTarget: "https://example.com/foo",
scope: "page",
});
- referringDomainsMock.mockResolvedValue([
- {
- domain: "source.example",
- backlinks: 4,
- referring_pages: 2,
- rank: 65,
- first_seen: "2026-01-01",
- broken_backlinks: 0,
- broken_pages: 0,
- backlinks_spam_score: 2,
- target_spam_score: 4,
- },
- ]);
- domainPagesMock.mockResolvedValue([
- {
- page: "https://example.com/foo",
- backlinks: 100,
- referring_domains: 20,
- rank: 50,
- broken_backlinks: 0,
- },
- ]);
+ referringDomainsMock.mockResolvedValue({
+ items: [
+ {
+ domain: "source.example",
+ backlinks: 4,
+ referring_pages: 2,
+ rank: 65,
+ first_seen: "2026-01-01",
+ broken_backlinks: 0,
+ broken_pages: 0,
+ backlinks_spam_score: 2,
+ target_spam_score: 4,
+ },
+ ],
+ totalCount: 1,
+ });
+ domainPagesMock.mockResolvedValue({
+ items: [
+ {
+ page: "https://example.com/foo",
+ backlinks: 100,
+ referring_domains: 20,
+ rank: 50,
+ broken_backlinks: 0,
+ },
+ ],
+ totalCount: 1,
+ });
- const domains = await service.profileReferringDomains(
- { target: "https://example.com/foo" },
+ const domains = await service.profileReferringDomainsPage(
+ {
+ ...pageInputDefaults,
+ target: "https://example.com/foo",
+ sortField: "backlinks",
+ },
billingCustomer,
);
- const pages = await service.profileTopPages(
- { target: "https://example.com/foo" },
+ const pages = await service.profileTopPagesPage(
+ {
+ ...pageInputDefaults,
+ target: "https://example.com/foo",
+ sortField: "backlinks",
+ },
billingCustomer,
);
expect(domains.rows).toHaveLength(1);
expect(domains.rows[0]?.spamScore).toBe(2);
+ expect(domains.hasMore).toBe(false);
expect(pages.rows).toHaveLength(1);
});
@@ -174,22 +274,29 @@ it("does not fall back to target spam score for referring domains", async () =>
displayTarget: "example.com",
scope: "domain",
});
- referringDomainsMock.mockResolvedValue([
- {
- domain: "source.example",
- backlinks: 4,
- referring_pages: 2,
- rank: 65,
- first_seen: "2026-01-01",
- broken_backlinks: 0,
- broken_pages: 0,
- backlinks_spam_score: null,
- target_spam_score: 4,
- },
- ]);
+ referringDomainsMock.mockResolvedValue({
+ items: [
+ {
+ domain: "source.example",
+ backlinks: 4,
+ referring_pages: 2,
+ rank: 65,
+ first_seen: "2026-01-01",
+ broken_backlinks: 0,
+ broken_pages: 0,
+ backlinks_spam_score: null,
+ target_spam_score: 4,
+ },
+ ],
+ totalCount: 1,
+ });
- const domains = await service.profileReferringDomains(
- { target: "example.com" },
+ const domains = await service.profileReferringDomainsPage(
+ {
+ ...pageInputDefaults,
+ target: "example.com",
+ sortField: "backlinks",
+ },
billingCustomer,
);
@@ -197,39 +304,33 @@ it("does not fall back to target spam score for referring domains", async () =>
expect(domains.rows[0]?.spamScore).toBeNull();
});
-it("keeps cache entries isolated per organization", async () => {
+it("keeps page cache entries isolated per page and per organization", async () => {
vi.mocked(normalizeBacklinksTarget).mockReturnValue({
apiTarget: "example.com",
displayTarget: "example.com",
scope: "domain",
});
- backlinksSummaryMock.mockResolvedValue({
- rank: 42,
- backlinks: 1200,
- referring_pages: 900,
- referring_domains: 320,
- broken_backlinks: 12,
- broken_pages: 3,
- backlinks_spam_score: 5,
- info: { target_spam_score: 4 },
- new_backlinks: 25,
- lost_backlinks: 10,
- new_referring_domains: 8,
- lost_referring_domains: 2,
- });
- backlinksRowsMock.mockResolvedValue([]);
- backlinksHistoryMock.mockResolvedValue([]);
+ backlinksRowsMock.mockResolvedValue({ items: [], totalCount: 0 });
- const input = { target: "example.com" };
+ const input = {
+ ...pageInputDefaults,
+ target: "example.com",
+ sortField: "rank",
+ } as const;
- await service.profileOverview(input, billingCustomer);
- await service.profileOverview(input, {
+ await service.profileBacklinksPage(input, billingCustomer);
+ await service.profileBacklinksPage(input, billingCustomer);
+ expect(backlinksRowsMock).toHaveBeenCalledTimes(1);
+
+ await service.profileBacklinksPage({ ...input, page: 2 }, billingCustomer);
+ expect(backlinksRowsMock).toHaveBeenCalledTimes(2);
+
+ await service.profileBacklinksPage(input, {
organizationId: "org_456",
userId: "user_456",
userEmail: "other@example.com",
});
-
- expect(backlinksSummaryMock).toHaveBeenCalledTimes(2);
+ expect(backlinksRowsMock).toHaveBeenCalledTimes(3);
});
function parseCachedValue(raw: string): unknown {
diff --git a/src/server/features/backlinks/services/BacklinksService.ts b/src/server/features/backlinks/services/BacklinksService.ts
index 37d40c9..5bdb604 100644
--- a/src/server/features/backlinks/services/BacklinksService.ts
+++ b/src/server/features/backlinks/services/BacklinksService.ts
@@ -2,37 +2,63 @@ import { buildCacheKey, getCached, setCached } from "@/server/lib/r2-cache";
import { normalizeBacklinksTarget } from "@/server/lib/dataforseo";
import {
normalizeBacklinksSpamFilterOptions,
+ type BacklinksLookupInput,
type BacklinksSpamFilterOptions,
} from "@/types/schemas/backlinks";
import {
profileBacklinksOverview,
- profileReferringDomainsRows,
- profileTopPagesRows,
+ profileBacklinksRowsPage,
+ profileReferringDomainsPage,
+ profileTopPagesPage,
type BacklinksCache,
+ type BacklinksRowsPageServiceInput,
+ type ReferringDomainsPageServiceInput,
+ type TopPagesPageServiceInput,
} from "@/server/features/backlinks/services/backlinksServiceData";
import type { BillingCustomerContext } from "@/server/billing/subscription";
-import type { BacklinksLookupInput } from "@/types/schemas/backlinks";
const defaultCache: BacklinksCache = {
get: getCached,
set: setCached,
};
+type BacklinksPageCacheInput = {
+ target: string;
+ scope?: "domain" | "page";
+ page: number;
+ pageSize: number;
+ sortField: string;
+ sortOrder: string;
+ filters: Record;
+ /** Backlinks rows only: DataForSEO result grouping. */
+ mode?: string;
+};
+
function createBacklinksService(cache: BacklinksCache = defaultCache) {
return {
async profileOverview(
input: BacklinksLookupInput,
billingCustomer: BillingCustomerContext,
+ ) {
+ const cacheKey = await buildCacheKey("backlinks:overview", {
+ ...buildTargetCacheInput(input, billingCustomer),
+ });
+
+ return profileBacklinksOverview(cache, cacheKey, input, billingCustomer);
+ },
+ async profileBacklinksPage(
+ input: BacklinksRowsPageServiceInput,
+ billingCustomer: BillingCustomerContext,
options?: BacklinksSpamFilterOptions,
) {
- const cacheKey = await buildBacklinksCacheKey(
- "backlinks:overview",
+ const cacheKey = await buildPageCacheKey(
+ "backlinks:rows-page",
input,
billingCustomer,
options,
);
- return profileBacklinksOverview(
+ return profileBacklinksRowsPage(
cache,
cacheKey,
input,
@@ -40,19 +66,19 @@ function createBacklinksService(cache: BacklinksCache = defaultCache) {
options,
);
},
- async profileReferringDomains(
- input: BacklinksLookupInput,
+ async profileReferringDomainsPage(
+ input: ReferringDomainsPageServiceInput,
billingCustomer: BillingCustomerContext,
options?: BacklinksSpamFilterOptions,
) {
- const cacheKey = await buildBacklinksCacheKey(
- "backlinks:referring-domains",
+ const cacheKey = await buildPageCacheKey(
+ "backlinks:referring-domains-page",
input,
billingCustomer,
options,
);
- return profileReferringDomainsRows(
+ return profileReferringDomainsPage(
cache,
cacheKey,
input,
@@ -60,44 +86,52 @@ function createBacklinksService(cache: BacklinksCache = defaultCache) {
options,
);
},
- async profileTopPages(
- input: BacklinksLookupInput,
+ async profileTopPagesPage(
+ input: TopPagesPageServiceInput,
billingCustomer: BillingCustomerContext,
) {
- const cacheKey = await buildBacklinksCacheKey(
- "backlinks:top-pages",
+ const cacheKey = await buildPageCacheKey(
+ "backlinks:top-pages-page",
input,
billingCustomer,
);
- return profileTopPagesRows(cache, cacheKey, input, billingCustomer);
+ return profileTopPagesPage(cache, cacheKey, input, billingCustomer);
},
} as const;
}
-async function buildBacklinksCacheKey(
- prefix: string,
+function buildTargetCacheInput(
input: BacklinksLookupInput,
billingCustomer: BillingCustomerContext,
- options?: BacklinksSpamFilterOptions,
-): Promise {
+) {
const normalizedTarget = normalizeBacklinksTarget(input.target, {
scope: input.scope,
});
- const cacheKeyInput = {
+
+ return {
organizationId: billingCustomer.organizationId,
target: normalizedTarget.apiTarget,
scope: normalizedTarget.scope,
};
+}
- if (!options) {
- return buildCacheKey(prefix, cacheKeyInput);
- }
-
+async function buildPageCacheKey(
+ prefix: string,
+ input: BacklinksPageCacheInput,
+ billingCustomer: BillingCustomerContext,
+ options?: BacklinksSpamFilterOptions,
+): Promise {
const spamFilterOptions = normalizeBacklinksSpamFilterOptions(options);
return buildCacheKey(prefix, {
- ...cacheKeyInput,
+ ...buildTargetCacheInput(input, billingCustomer),
+ page: input.page,
+ pageSize: input.pageSize,
+ sortField: input.sortField,
+ sortOrder: input.sortOrder,
+ filters: input.filters,
+ ...(input.mode ? { mode: input.mode } : {}),
hideSpam: String(spamFilterOptions.hideSpam),
...(spamFilterOptions.hideSpam
? { spamThreshold: String(spamFilterOptions.spamThreshold) }
diff --git a/src/server/features/backlinks/services/backlinksApiFilters.test.ts b/src/server/features/backlinks/services/backlinksApiFilters.test.ts
new file mode 100644
index 0000000..60c819d
--- /dev/null
+++ b/src/server/features/backlinks/services/backlinksApiFilters.test.ts
@@ -0,0 +1,152 @@
+import { describe, expect, it } from "vitest";
+import {
+ countFilterConditions,
+ toBacklinksFiltersPayload,
+ type BacklinksTabFilterValues,
+ EMPTY_BACKLINKS_FILTERS,
+} from "@/client/features/backlinks/backlinksFilterTypes";
+import {
+ buildBacklinksRowsApiFilters,
+ buildReferringDomainsApiFilters,
+ buildTopPagesApiFilters,
+} from "./backlinksApiFilters";
+
+describe("buildBacklinksRowsApiFilters", () => {
+ it("ORs include terms in one group and ANDs everything else", () => {
+ expect(
+ buildBacklinksRowsApiFilters({
+ include: "blog, news",
+ exclude: "spam",
+ minDomainRank: 30,
+ linkType: "dofollow",
+ hideLost: true,
+ }),
+ ).toEqual([
+ [["url_from", "ilike", "%blog%"], "or", ["url_from", "ilike", "%news%"]],
+ "and",
+ ["url_from", "not_ilike", "%spam%"],
+ "and",
+ ["domain_from_rank", ">=", 30],
+ "and",
+ ["dofollow", "=", true],
+ "and",
+ ["is_lost", "=", false],
+ ]);
+ });
+
+ it("emits a single include term as a plain condition", () => {
+ expect(buildBacklinksRowsApiFilters({ include: "blog" })).toEqual([
+ ["url_from", "ilike", "%blog%"],
+ ]);
+ });
+
+ it("escapes LIKE wildcards in terms", () => {
+ expect(buildBacklinksRowsApiFilters({ include: "wp_content" })).toEqual([
+ ["url_from", "ilike", "%wp\\_content%"],
+ ]);
+ });
+
+ it("returns no expressions for empty filters", () => {
+ expect(buildBacklinksRowsApiFilters({})).toEqual([]);
+ });
+
+ it("throws when the condition budget is exceeded", () => {
+ expect(() =>
+ buildBacklinksRowsApiFilters({
+ include: "a, b, c, d, e",
+ exclude: "f, g, h, i",
+ }),
+ ).toThrowError(/Too many filter conditions/);
+ });
+});
+
+describe("buildReferringDomainsApiFilters", () => {
+ it("filters on referring-domain fields", () => {
+ expect(
+ buildReferringDomainsApiFilters({
+ include: "edu",
+ minBacklinks: 5,
+ maxSpamScore: 30,
+ }),
+ ).toEqual([
+ ["domain", "ilike", "%edu%"],
+ "and",
+ ["backlinks", ">=", 5],
+ "and",
+ ["backlinks_spam_score", "<=", 30],
+ ]);
+ });
+});
+
+describe("buildTopPagesApiFilters", () => {
+ it("filters on the url field", () => {
+ expect(
+ buildTopPagesApiFilters({ include: "/blog", minReferringDomains: 2 }),
+ ).toEqual([
+ ["url", "ilike", "%/blog%"],
+ "and",
+ ["referring_domains", ">=", 2],
+ ]);
+ });
+});
+
+describe("client condition count vs server condition budget", () => {
+ // The client gates Apply with countFilterConditions; the server enforces the
+ // DataForSEO budget while building. They must agree on how many conditions a
+ // set of filter values produces, or users get hard errors the UI accepted.
+ function serverConditionCount(values: BacklinksTabFilterValues): number {
+ const expressions = buildBacklinksRowsApiFilters(
+ toBacklinksFiltersPayload(values),
+ );
+ let count = 0;
+ for (const expression of expressions) {
+ if (expression === "and") continue;
+ // An include OR-group contains nested clauses and "or" connectors.
+ count +=
+ Array.isArray(expression) && Array.isArray(expression[0])
+ ? Math.ceil(expression.length / 2)
+ : 1;
+ }
+ return count;
+ }
+
+ const cases: Array<[string, BacklinksTabFilterValues]> = [
+ ["empty", { ...EMPTY_BACKLINKS_FILTERS }],
+ [
+ "terms and ranges",
+ {
+ ...EMPTY_BACKLINKS_FILTERS,
+ include: "blog, news",
+ exclude: "spam",
+ minDomainRank: "30",
+ maxSpamScore: "50",
+ },
+ ],
+ [
+ "toggles",
+ {
+ ...EMPTY_BACKLINKS_FILTERS,
+ linkType: "nofollow",
+ hideLost: "true",
+ hideBroken: "true",
+ },
+ ],
+ [
+ "everything",
+ {
+ ...EMPTY_BACKLINKS_FILTERS,
+ include: "a",
+ exclude: "b",
+ minDomainRank: "1",
+ maxDomainRank: "90",
+ minLinkAuthority: "2",
+ linkType: "dofollow",
+ hideLost: "true",
+ },
+ ],
+ ];
+
+ it.each(cases)("matches for %s", (_name, values) => {
+ expect(serverConditionCount(values)).toBe(countFilterConditions(values));
+ });
+});
diff --git a/src/server/features/backlinks/services/backlinksApiFilters.ts b/src/server/features/backlinks/services/backlinksApiFilters.ts
new file mode 100644
index 0000000..6a19b54
--- /dev/null
+++ b/src/server/features/backlinks/services/backlinksApiFilters.ts
@@ -0,0 +1,179 @@
+import {
+ assertFilterConditionBudget,
+ buildIncludeOrGroup,
+ collectNumericRange,
+ escapeLikeTerm,
+ joinClauses,
+ parseFilterTerms,
+ type FilterClause,
+} from "@/server/lib/dataforseo/filters";
+import type {
+ BacklinksRowsFilters,
+ BacklinksRowsSortField,
+ BacklinksSortOrder,
+ ReferringDomainsFilters,
+ ReferringDomainsSortField,
+ TopPagesFilters,
+ TopPagesSortField,
+} from "@/types/schemas/backlinks";
+
+const BACKLINKS_ROWS_SORT_FIELDS: Record = {
+ rank: "rank",
+ domainRank: "domain_from_rank",
+ spamScore: "backlink_spam_score",
+ firstSeen: "first_seen",
+};
+
+const REFERRING_DOMAINS_SORT_FIELDS: Record =
+ {
+ domain: "domain",
+ backlinks: "backlinks",
+ referringPages: "referring_pages",
+ rank: "rank",
+ spamScore: "backlinks_spam_score",
+ firstSeen: "first_seen",
+ brokenBacklinks: "broken_backlinks",
+ };
+
+const TOP_PAGES_SORT_FIELDS: Record = {
+ backlinks: "backlinks",
+ referringDomains: "referring_domains",
+ rank: "rank",
+ brokenBacklinks: "broken_backlinks",
+};
+
+export function buildBacklinksRowsOrderBy(
+ field: BacklinksRowsSortField,
+ order: BacklinksSortOrder,
+): string[] {
+ return [`${BACKLINKS_ROWS_SORT_FIELDS[field]},${order}`];
+}
+
+export function buildReferringDomainsOrderBy(
+ field: ReferringDomainsSortField,
+ order: BacklinksSortOrder,
+): string[] {
+ return [`${REFERRING_DOMAINS_SORT_FIELDS[field]},${order}`];
+}
+
+export function buildTopPagesOrderBy(
+ field: TopPagesSortField,
+ order: BacklinksSortOrder,
+): string[] {
+ return [`${TOP_PAGES_SORT_FIELDS[field]},${order}`];
+}
+
+/**
+ * Translates the Backlinks tab filters into DataForSEO filter expressions.
+ * Include/exclude terms match the source URL (which contains the linking
+ * domain): include terms are OR'd (match any), exclude terms AND'd (drop all).
+ */
+export function buildBacklinksRowsApiFilters(
+ filters: BacklinksRowsFilters,
+): unknown[] {
+ const conditions: FilterClause[] = [];
+
+ collectExcludeConditions(conditions, "url_from", filters.exclude);
+ collectNumericRange(
+ conditions,
+ "domain_from_rank",
+ filters.minDomainRank,
+ filters.maxDomainRank,
+ );
+ collectNumericRange(
+ conditions,
+ "rank",
+ filters.minLinkAuthority,
+ filters.maxLinkAuthority,
+ );
+ collectNumericRange(
+ conditions,
+ "backlink_spam_score",
+ filters.minSpamScore,
+ filters.maxSpamScore,
+ );
+ if (filters.linkType) {
+ conditions.push(["dofollow", "=", filters.linkType === "dofollow"]);
+ }
+ if (filters.hideLost) {
+ conditions.push(["is_lost", "=", false]);
+ }
+ if (filters.hideBroken) {
+ conditions.push(["is_broken", "=", false]);
+ }
+ if (filters.domainFrom) {
+ conditions.push(["domain_from", "=", filters.domainFrom]);
+ }
+
+ return finishFilters("url_from", filters.include, conditions);
+}
+
+export function buildReferringDomainsApiFilters(
+ filters: ReferringDomainsFilters,
+): unknown[] {
+ const conditions: FilterClause[] = [];
+
+ collectExcludeConditions(conditions, "domain", filters.exclude);
+ collectNumericRange(
+ conditions,
+ "backlinks",
+ filters.minBacklinks,
+ filters.maxBacklinks,
+ );
+ collectNumericRange(conditions, "rank", filters.minRank, filters.maxRank);
+ collectNumericRange(
+ conditions,
+ "backlinks_spam_score",
+ filters.minSpamScore,
+ filters.maxSpamScore,
+ );
+
+ return finishFilters("domain", filters.include, conditions);
+}
+
+export function buildTopPagesApiFilters(filters: TopPagesFilters): unknown[] {
+ const conditions: FilterClause[] = [];
+
+ collectExcludeConditions(conditions, "url", filters.exclude);
+ collectNumericRange(
+ conditions,
+ "backlinks",
+ filters.minBacklinks,
+ filters.maxBacklinks,
+ );
+ collectNumericRange(
+ conditions,
+ "referring_domains",
+ filters.minReferringDomains,
+ filters.maxReferringDomains,
+ );
+ collectNumericRange(conditions, "rank", filters.minRank, filters.maxRank);
+
+ return finishFilters("url", filters.include, conditions);
+}
+
+function collectExcludeConditions(
+ out: FilterClause[],
+ field: string,
+ exclude: string | undefined,
+) {
+ for (const term of parseFilterTerms(exclude)) {
+ out.push([field, "not_ilike", `%${escapeLikeTerm(term)}%`]);
+ }
+}
+
+/** Prepends the OR'd include group, enforces the condition budget, joins with "and". */
+function finishFilters(
+ includeField: string,
+ include: string | undefined,
+ conditions: FilterClause[],
+): unknown[] {
+ const includeGroup = buildIncludeOrGroup(includeField, include);
+ assertFilterConditionBudget(
+ conditions.length + (includeGroup?.conditionCount ?? 0),
+ );
+ return joinClauses(
+ includeGroup ? [includeGroup.clause, ...conditions] : conditions,
+ "and",
+ );
+}
diff --git a/src/server/features/backlinks/services/backlinksOverviewSchema.ts b/src/server/features/backlinks/services/backlinksOverviewSchema.ts
index c656860..071445a 100644
--- a/src/server/features/backlinks/services/backlinksOverviewSchema.ts
+++ b/src/server/features/backlinks/services/backlinksOverviewSchema.ts
@@ -19,7 +19,7 @@ const backlinksRowSchema = z.object({
linksCount: z.number().nullable(),
});
-export const referringDomainRowSchema = z.object({
+const referringDomainRowSchema = z.object({
domain: z.string().nullable(),
backlinks: z.number().nullable(),
referringPages: z.number().nullable(),
@@ -30,7 +30,7 @@ export const referringDomainRowSchema = z.object({
brokenPages: z.number().nullable(),
});
-export const topPageRowSchema = z.object({
+const topPageRowSchema = z.object({
page: z.string().nullable(),
backlinks: z.number().nullable(),
referringDomains: z.number().nullable(),
@@ -71,12 +71,35 @@ export const backlinksOverviewSchema = z.object({
newReferringDomains: z.number().nullable(),
lostReferringDomains: z.number().nullable(),
}),
- backlinks: z.array(backlinksRowSchema),
- referringDomains: z.array(referringDomainRowSchema),
- topPages: z.array(topPageRowSchema),
trends: z.array(backlinksTrendRowSchema),
newLostTrends: z.array(backlinksNewLostTrendRowSchema),
fetchedAt: z.string(),
});
export type BacklinksOverviewResult = z.infer;
+
+function buildPageResultSchema(rowSchema: T) {
+ return z.object({
+ rows: z.array(rowSchema),
+ totalCount: z.number().nullable(),
+ hasMore: z.boolean(),
+ page: z.number(),
+ pageSize: z.number(),
+ fetchedAt: z.string(),
+ });
+}
+
+export const backlinksRowsPageResultSchema =
+ buildPageResultSchema(backlinksRowSchema);
+export const referringDomainsPageResultSchema = buildPageResultSchema(
+ referringDomainRowSchema,
+);
+export const topPagesPageResultSchema = buildPageResultSchema(topPageRowSchema);
+
+export type BacklinksRowsPageResult = z.infer<
+ typeof backlinksRowsPageResultSchema
+>;
+export type ReferringDomainsPageResult = z.infer<
+ typeof referringDomainsPageResultSchema
+>;
+export type TopPagesPageResult = z.infer;
diff --git a/src/server/features/backlinks/services/backlinksServiceData.ts b/src/server/features/backlinks/services/backlinksServiceData.ts
index 6157c84..0927a9b 100644
--- a/src/server/features/backlinks/services/backlinksServiceData.ts
+++ b/src/server/features/backlinks/services/backlinksServiceData.ts
@@ -9,21 +9,52 @@ import {
type DomainPageSummaryItem,
type ReferringDomainItem,
} from "@/server/lib/dataforseo";
-import {
- normalizeBacklinksSpamFilterOptions,
- type BacklinksSpamFilterOptions,
+import type {
+ BacklinksLookupInput,
+ BacklinksRowsPageInput,
+ BacklinksSpamFilterOptions,
+ ReferringDomainsPageInput,
+ TopPagesPageInput,
} from "@/types/schemas/backlinks";
+
import {
backlinksOverviewSchema,
- referringDomainRowSchema,
- topPageRowSchema,
+ backlinksRowsPageResultSchema,
+ referringDomainsPageResultSchema,
+ topPagesPageResultSchema,
type BacklinksOverviewResult,
+ type BacklinksRowsPageResult,
+ type ReferringDomainsPageResult,
+ type TopPagesPageResult,
} from "@/server/features/backlinks/services/backlinksOverviewSchema";
-import type { BacklinksLookupInput } from "@/types/schemas/backlinks";
+import {
+ buildBacklinksRowsApiFilters,
+ buildBacklinksRowsOrderBy,
+ buildReferringDomainsApiFilters,
+ buildReferringDomainsOrderBy,
+ buildTopPagesApiFilters,
+ buildTopPagesOrderBy,
+} from "@/server/features/backlinks/services/backlinksApiFilters";
+
+// The page-request schemas carry projectId for the web middleware; the
+// service layer is organization-scoped and never reads it.
+export type BacklinksRowsPageServiceInput = Omit<
+ BacklinksRowsPageInput,
+ "projectId"
+>;
+export type ReferringDomainsPageServiceInput = Omit<
+ ReferringDomainsPageInput,
+ "projectId"
+>;
+export type TopPagesPageServiceInput = Omit;
const BACKLINKS_OVERVIEW_TTL_SECONDS = 6 * 60 * 60;
const BACKLINKS_TAB_TTL_SECONDS = 6 * 60 * 60;
+const backlinksOverviewCacheSchema = z.object({
+ overview: backlinksOverviewSchema,
+});
+
export type BacklinksCache = {
get(key: string): Promise;
set(key: string, data: unknown, ttlSeconds: number): Promise;
@@ -33,24 +64,6 @@ type BacklinksOverviewProfile = {
overview: BacklinksOverviewResult;
};
-type ReferringDomainsProfile = {
- rows: BacklinksOverviewResult["referringDomains"];
-};
-
-type TopPagesProfile = {
- rows: BacklinksOverviewResult["topPages"];
-};
-
-const backlinksOverviewCacheSchema = z.object({
- overview: backlinksOverviewSchema,
-});
-
-const referringDomainsCacheSchema = z.object({
- rows: z.array(referringDomainRowSchema),
-});
-
-const topPagesCacheSchema = z.object({ rows: z.array(topPageRowSchema) });
-
type BacklinksDateRange = {
dateFrom: string;
dateTo: string;
@@ -61,10 +74,10 @@ export async function profileBacklinksOverview(
cacheKey: string,
input: BacklinksLookupInput,
billingCustomer: BillingCustomerContext,
- options?: BacklinksSpamFilterOptions,
): Promise {
- const cachedRaw = await cache.get(cacheKey);
- const cached = backlinksOverviewCacheSchema.safeParse(cachedRaw);
+ const cached = backlinksOverviewCacheSchema.safeParse(
+ await cache.get(cacheKey),
+ );
if (cached.success) {
return {
overview: cached.data.overview,
@@ -77,16 +90,10 @@ export async function profileBacklinksOverview(
const normalizedTarget = normalizeBacklinksTarget(input.target, {
scope: input.scope,
});
- const request = buildBacklinksListRequest(
- normalizedTarget.apiTarget,
- 100,
- options,
- );
const dateRange = buildBacklinksDateRange(now);
- const [summary, backlinks, history] = await Promise.all([
- dataforseo.backlinks.summary({ target: request.target }),
- dataforseo.backlinks.rows(request),
+ const [summary, history] = await Promise.all([
+ dataforseo.backlinks.summary({ target: normalizedTarget.apiTarget }),
normalizedTarget.scope === "domain"
? dataforseo.backlinks.history({
target: normalizedTarget.apiTarget,
@@ -99,7 +106,6 @@ export async function profileBacklinksOverview(
normalizedTarget,
now,
summary,
- backlinks,
history,
});
await cacheValue(
@@ -112,76 +118,131 @@ export async function profileBacklinksOverview(
return { overview };
}
-export async function profileReferringDomainsRows(
+export async function profileBacklinksRowsPage(
cache: BacklinksCache,
cacheKey: string,
- input: BacklinksLookupInput,
+ input: BacklinksRowsPageServiceInput,
billingCustomer: BillingCustomerContext,
- options?: BacklinksSpamFilterOptions,
-): Promise {
- const cachedRaw = await cache.get(cacheKey);
- const cached = referringDomainsCacheSchema.safeParse(cachedRaw);
- if (cached.success) {
- return {
- rows: cached.data.rows,
- };
- }
-
- const dataforseo = createDataforseoClient(billingCustomer);
-
- const request = buildBacklinksListRequest(
- normalizeBacklinksTarget(input.target, { scope: input.scope }).apiTarget,
- 100,
- options,
+ spamOptions?: BacklinksSpamFilterOptions,
+): Promise {
+ const cached = backlinksRowsPageResultSchema.safeParse(
+ await cache.get(cacheKey),
);
- const response = await dataforseo.backlinks.referringDomains(request);
- const rows = mapReferringDomainsRows(response);
-
- await cacheValue(cache, cacheKey, { rows }, BACKLINKS_TAB_TTL_SECONDS);
-
- return { rows };
-}
-
-export async function profileTopPagesRows(
- cache: BacklinksCache,
- cacheKey: string,
- input: BacklinksLookupInput,
- billingCustomer: BillingCustomerContext,
-): Promise {
- const cachedRaw = await cache.get(cacheKey);
- const cached = topPagesCacheSchema.safeParse(cachedRaw);
if (cached.success) {
- return {
- rows: cached.data.rows,
- };
+ return cached.data;
}
const dataforseo = createDataforseoClient(billingCustomer);
+ const offset = (input.page - 1) * input.pageSize;
+ const filters = buildBacklinksRowsApiFilters(input.filters);
- const request = {
+ const response = await dataforseo.backlinks.rows({
target: normalizeBacklinksTarget(input.target, { scope: input.scope })
.apiTarget,
- };
- const response = await dataforseo.backlinks.domainPages({
- ...request,
- limit: 100,
+ limit: input.pageSize,
+ offset,
+ orderBy: buildBacklinksRowsOrderBy(input.sortField, input.sortOrder),
+ filters: filters.length > 0 ? filters : undefined,
+ mode: input.mode,
+ ...spamOptions,
});
- const rows = mapTopPagesRows(response);
- await cacheValue(cache, cacheKey, { rows }, BACKLINKS_TAB_TTL_SECONDS);
+ const result = buildPageResult(input, offset, {
+ rows: mapBacklinksRows(response.items),
+ totalCount: response.totalCount,
+ });
+ await cacheValue(cache, cacheKey, result, BACKLINKS_TAB_TTL_SECONDS);
- return { rows };
+ return result;
}
-function buildBacklinksListRequest(
- target: string,
- limit: number,
- options?: BacklinksSpamFilterOptions,
+export async function profileReferringDomainsPage(
+ cache: BacklinksCache,
+ cacheKey: string,
+ input: ReferringDomainsPageServiceInput,
+ billingCustomer: BillingCustomerContext,
+ spamOptions?: BacklinksSpamFilterOptions,
+): Promise {
+ const cached = referringDomainsPageResultSchema.safeParse(
+ await cache.get(cacheKey),
+ );
+ if (cached.success) {
+ return cached.data;
+ }
+
+ const dataforseo = createDataforseoClient(billingCustomer);
+ const offset = (input.page - 1) * input.pageSize;
+ const filters = buildReferringDomainsApiFilters(input.filters);
+
+ const response = await dataforseo.backlinks.referringDomains({
+ target: normalizeBacklinksTarget(input.target, { scope: input.scope })
+ .apiTarget,
+ limit: input.pageSize,
+ offset,
+ orderBy: buildReferringDomainsOrderBy(input.sortField, input.sortOrder),
+ filters: filters.length > 0 ? filters : undefined,
+ ...spamOptions,
+ });
+
+ const result = buildPageResult(input, offset, {
+ rows: mapReferringDomainsRows(response.items),
+ totalCount: response.totalCount,
+ });
+ await cacheValue(cache, cacheKey, result, BACKLINKS_TAB_TTL_SECONDS);
+
+ return result;
+}
+
+export async function profileTopPagesPage(
+ cache: BacklinksCache,
+ cacheKey: string,
+ input: TopPagesPageServiceInput,
+ billingCustomer: BillingCustomerContext,
+): Promise {
+ const cached = topPagesPageResultSchema.safeParse(await cache.get(cacheKey));
+ if (cached.success) {
+ return cached.data;
+ }
+
+ const dataforseo = createDataforseoClient(billingCustomer);
+ const offset = (input.page - 1) * input.pageSize;
+ const filters = buildTopPagesApiFilters(input.filters);
+
+ const response = await dataforseo.backlinks.domainPages({
+ target: normalizeBacklinksTarget(input.target, { scope: input.scope })
+ .apiTarget,
+ limit: input.pageSize,
+ offset,
+ orderBy: buildTopPagesOrderBy(input.sortField, input.sortOrder),
+ filters: filters.length > 0 ? filters : undefined,
+ });
+
+ const result = buildPageResult(input, offset, {
+ rows: mapTopPagesRows(response.items),
+ totalCount: response.totalCount,
+ });
+ await cacheValue(cache, cacheKey, result, BACKLINKS_TAB_TTL_SECONDS);
+
+ return result;
+}
+
+function buildPageResult(
+ input: { page: number; pageSize: number },
+ offset: number,
+ data: { rows: TRow[]; totalCount: number | null },
) {
+ const hasMore =
+ data.totalCount != null
+ ? offset + data.rows.length < data.totalCount
+ : data.rows.length === input.pageSize;
+
return {
- target,
- limit,
- ...normalizeBacklinksSpamFilterOptions(options),
+ rows: data.rows,
+ totalCount: data.totalCount,
+ hasMore,
+ page: input.page,
+ pageSize: input.pageSize,
+ fetchedAt: new Date().toISOString(),
};
}
@@ -205,7 +266,6 @@ function buildOverviewResult(args: {
normalizedTarget: ReturnType;
now: Date;
summary: BacklinksSummaryItem;
- backlinks: BacklinksItem[];
history: BacklinksHistoryItem[];
}): BacklinksOverviewResult {
const historyRows = args.history
@@ -253,9 +313,6 @@ function buildOverviewResult(args: {
args.summary.lost_reffering_domains ??
null,
},
- backlinks: mapBacklinksRows(args.backlinks),
- referringDomains: [],
- topPages: [],
trends: historyRows.map((item) => ({
date: item.date,
backlinks: item.backlinks,
diff --git a/src/server/features/domain/services/domainKeywordFilters.ts b/src/server/features/domain/services/domainKeywordFilters.ts
index 778f061..e54bb70 100644
--- a/src/server/features/domain/services/domainKeywordFilters.ts
+++ b/src/server/features/domain/services/domainKeywordFilters.ts
@@ -1,8 +1,12 @@
import {
- MAX_DATAFORSEO_FILTER_CONDITIONS,
- type DomainKeywordsFilters,
-} from "@/types/schemas/domain";
-import { AppError } from "@/server/lib/errors";
+ assertFilterConditionBudget,
+ collectNumericRange,
+ escapeLikeTerm,
+ joinClauses,
+ parseFilterTerms,
+ type FilterClause,
+} from "@/server/lib/dataforseo/filters";
+import type { DomainKeywordsFilters } from "@/types/schemas/domain";
export type DomainKeywordsSortMode =
| "rank"
@@ -27,62 +31,26 @@ export function buildOrderBy(
return [`${SORT_FIELD_BY_MODE[sortMode]},${sortOrder}`];
}
-function escapeLikeTerm(term: string): string {
- return term.replace(/[\\%_]/g, (match) => `\\${match}`);
-}
-
-function pushAnd(filters: unknown[], expression: Clause) {
- if (filters.length > 0) filters.push("and");
- filters.push(expression);
-}
-
-function parseTerms(value: string | undefined): string[] {
- if (!value) return [];
- return value
- .toLowerCase()
- .split(/[,+]/)
- .map((term) => term.trim())
- .filter(Boolean);
-}
-
-function collectNumericRange(
- out: Clause[],
- field: string,
- min: number | undefined,
- max: number | undefined,
-) {
- if (typeof min === "number" && Number.isFinite(min)) {
- out.push([field, ">=", min]);
- }
- if (typeof max === "number" && Number.isFinite(max)) {
- out.push([field, "<=", max]);
- }
-}
-
/**
- * DataForSEO accepts up to 8 filter conditions per request joined by
- * "and"/"or" operators. Each include/exclude term is one ilike clause;
- * numeric ranges add one per bound; the free-text search term adds one OR-
- * group of two (keyword OR url). The client surfaces the same condition
- * count and disables Apply when over budget, so reaching the cap here
- * indicates a misbehaving client — we throw rather than silently truncate.
+ * Each include/exclude term is one ilike clause; numeric ranges add one per
+ * bound; the free-text search term adds one OR-group of two (keyword OR url).
+ * The client surfaces the same condition count and disables Apply when over
+ * the DataForSEO budget.
*/
-type Clause = unknown[];
-
export function buildKeywordFilters(
filters: DomainKeywordsFilters,
searchTerm?: string,
): unknown[] {
- const conditions: Clause[] = [];
+ const conditions: FilterClause[] = [];
- for (const term of parseTerms(filters.include)) {
+ for (const term of parseFilterTerms(filters.include)) {
conditions.push([
"keyword_data.keyword",
"ilike",
`%${escapeLikeTerm(term)}%`,
]);
}
- for (const term of parseTerms(filters.exclude)) {
+ for (const term of parseFilterTerms(filters.exclude)) {
conditions.push([
"keyword_data.keyword",
"not_ilike",
@@ -125,21 +93,15 @@ export function buildKeywordFilters(
const searchGroup = trimmedSearch ? buildSearchGroup(trimmedSearch) : null;
// The search OR-group costs 2 slots; everything else is 1.
- const totalConditions = conditions.length + (searchGroup ? 2 : 0);
- if (totalConditions > MAX_DATAFORSEO_FILTER_CONDITIONS) {
- throw new AppError(
- "VALIDATION_ERROR",
- `Too many filter conditions (${totalConditions} of ${MAX_DATAFORSEO_FILTER_CONDITIONS} max).`,
- );
- }
+ assertFilterConditionBudget(conditions.length + (searchGroup ? 2 : 0));
- const expressions: unknown[] = [];
- for (const clause of conditions) pushAnd(expressions, clause);
- if (searchGroup) pushAnd(expressions, searchGroup);
- return expressions;
+ return joinClauses(
+ searchGroup ? [...conditions, searchGroup] : conditions,
+ "and",
+ );
}
-function buildSearchGroup(term: string): Clause {
+function buildSearchGroup(term: string): FilterClause {
const escaped = escapeLikeTerm(term);
return [
["keyword_data.keyword", "ilike", `%${escaped}%`],
diff --git a/src/server/lib/dataforseo/backlinks.test.ts b/src/server/lib/dataforseo/backlinks.test.ts
index 9b976af..585ffbd 100644
--- a/src/server/lib/dataforseo/backlinks.test.ts
+++ b/src/server/lib/dataforseo/backlinks.test.ts
@@ -209,7 +209,7 @@ describe("fetchBacklinksSummary", () => {
await expect(
fetchBacklinksRows({ target: "example.com" }),
- ).resolves.toMatchObject({ data: [] });
+ ).resolves.toMatchObject({ data: { items: [], totalCount: null } });
await expect(
fetchBacklinksHistory({
target: "example.com",
diff --git a/src/server/lib/dataforseo/backlinks.ts b/src/server/lib/dataforseo/backlinks.ts
index cd8d402..ea4491b 100644
--- a/src/server/lib/dataforseo/backlinks.ts
+++ b/src/server/lib/dataforseo/backlinks.ts
@@ -17,6 +17,7 @@ import {
assertOk,
buildTaskBilling,
parseTaskItems,
+ parseTaskTotalCount,
type DataforseoApiResponse,
} from "@/server/lib/dataforseo/envelope";
@@ -24,7 +25,16 @@ export { normalizeBacklinksTarget } from "@/server/lib/dataforseoBacklinksTarget
type BacklinksRequest = { target: string };
type BacklinksListRequest = BacklinksRequest &
- BacklinksSpamFilterOptions & { limit?: number };
+ BacklinksSpamFilterOptions & {
+ limit?: number;
+ offset?: number;
+ /** DataForSEO order_by entries, e.g. ["rank,desc"]. */
+ orderBy?: string[];
+ /** Pre-built DataForSEO filter expressions, already joined with and/or. */
+ filters?: unknown[];
+ /** Result grouping (backlinks list only): "one_per_domain" | "as_is". */
+ mode?: string;
+ };
type BacklinksTimeseriesRequest = {
target: string;
dateFrom: string;
@@ -146,6 +156,24 @@ function buildCommonPayload(input: BacklinksRequest) {
const assertOptions = (path: string) =>
({ classify: classifyBacklinksError, classifyPath: path }) as const;
+/**
+ * Joins caller-provided filter expressions with the spam-score condition.
+ * `userFilters` arrives already and/or-joined, so the spam condition is
+ * appended with a single top-level "and".
+ */
+function combineFilters(
+ userFilters: unknown[] | undefined,
+ spamCondition: unknown[] | undefined,
+): unknown[] | undefined {
+ const merged: unknown[] = [];
+ if (userFilters && userFilters.length > 0) merged.push(...userFilters);
+ if (spamCondition) {
+ if (merged.length > 0) merged.push("and");
+ merged.push(spamCondition);
+ }
+ return merged.length > 0 ? merged : undefined;
+}
+
export async function fetchBacklinksSummary(input: BacklinksRequest) {
const response = await backlinksApi(classifyBacklinksError).summaryLive([
new BacklinksSummaryLiveRequestInfo(buildCommonPayload(input)),
@@ -179,14 +207,19 @@ export async function fetchBacklinksSummary(input: BacklinksRequest) {
export async function fetchBacklinksRows(input: BacklinksListRequest) {
const spamFilterOptions = normalizeBacklinksSpamFilterOptions(input);
- const filters = spamFilterOptions.hideSpam
- ? [["backlink_spam_score", "<=", spamFilterOptions.spamThreshold]]
- : undefined;
+ const filters = combineFilters(
+ input.filters,
+ spamFilterOptions.hideSpam
+ ? ["backlink_spam_score", "<=", spamFilterOptions.spamThreshold]
+ : undefined,
+ );
const response = await backlinksApi(classifyBacklinksError).backlinksLive([
new BacklinksBacklinksLiveRequestInfo({
...buildCommonPayload(input),
limit: input.limit ?? 100,
- order_by: ["rank,desc"],
+ offset: input.offset,
+ order_by: input.orderBy ?? ["rank,desc"],
+ mode: input.mode,
...(filters ? { filters } : {}),
}),
]);
@@ -195,23 +228,30 @@ export async function fetchBacklinksRows(input: BacklinksListRequest) {
assertOptions("/v3/backlinks/backlinks/live"),
);
return {
- data: parseTaskItems("backlinks-live", task, backlinksItemSchema),
+ data: {
+ items: parseTaskItems("backlinks-live", task, backlinksItemSchema),
+ totalCount: parseTaskTotalCount(task),
+ },
billing: buildTaskBilling(task),
};
}
export async function fetchReferringDomains(input: BacklinksListRequest) {
const spamFilterOptions = normalizeBacklinksSpamFilterOptions(input);
- const filters = spamFilterOptions.hideSpam
- ? [["backlinks_spam_score", "<=", spamFilterOptions.spamThreshold]]
- : undefined;
+ const filters = combineFilters(
+ input.filters,
+ spamFilterOptions.hideSpam
+ ? ["backlinks_spam_score", "<=", spamFilterOptions.spamThreshold]
+ : undefined,
+ );
const response = await backlinksApi(
classifyBacklinksError,
).referringDomainsLive([
new BacklinksReferringDomainsLiveRequestInfo({
...buildCommonPayload(input),
limit: input.limit ?? 100,
- order_by: ["backlinks,desc"],
+ offset: input.offset,
+ order_by: input.orderBy ?? ["backlinks,desc"],
...(filters ? { filters } : {}),
}),
]);
@@ -220,23 +260,30 @@ export async function fetchReferringDomains(input: BacklinksListRequest) {
assertOptions("/v3/backlinks/referring_domains/live"),
);
return {
- data: parseTaskItems(
- "referring-domains-live",
- task,
- referringDomainItemSchema,
- ),
+ data: {
+ items: parseTaskItems(
+ "referring-domains-live",
+ task,
+ referringDomainItemSchema,
+ ),
+ totalCount: parseTaskTotalCount(task),
+ },
billing: buildTaskBilling(task),
};
}
export async function fetchDomainPagesSummary(input: BacklinksListRequest) {
+ const filters =
+ input.filters && input.filters.length > 0 ? input.filters : undefined;
const response = await backlinksApi(
classifyBacklinksError,
).domainPagesSummaryLive([
new BacklinksDomainPagesSummaryLiveRequestInfo({
...buildCommonPayload(input),
limit: input.limit ?? 100,
- order_by: ["backlinks,desc"],
+ offset: input.offset,
+ order_by: input.orderBy ?? ["backlinks,desc"],
+ ...(filters ? { filters } : {}),
}),
]);
const task = assertOk(
@@ -244,11 +291,14 @@ export async function fetchDomainPagesSummary(input: BacklinksListRequest) {
assertOptions("/v3/backlinks/domain_pages_summary/live"),
);
return {
- data: parseTaskItems(
- "domain-pages-summary-live",
- task,
- domainPageSummaryItemSchema,
- ),
+ data: {
+ items: parseTaskItems(
+ "domain-pages-summary-live",
+ task,
+ domainPageSummaryItemSchema,
+ ),
+ totalCount: parseTaskTotalCount(task),
+ },
billing: buildTaskBilling(task),
};
}
diff --git a/src/server/lib/dataforseo/envelope.ts b/src/server/lib/dataforseo/envelope.ts
index bcb90c8..e572736 100644
--- a/src/server/lib/dataforseo/envelope.ts
+++ b/src/server/lib/dataforseo/envelope.ts
@@ -148,6 +148,13 @@ export function isRecord(value: unknown): value is Record {
return typeof value === "object" && value !== null;
}
+/** Reads `task.result[0].total_count` for paginated list endpoints. */
+export function parseTaskTotalCount(task: DataforseoTaskLike): number | null {
+ const first = task.result?.[0];
+ if (!isRecord(first)) return null;
+ return typeof first.total_count === "number" ? first.total_count : null;
+}
+
/** Reads `task.result[0].items`, validating against a Zod schema for loosely-typed endpoints. */
export function parseTaskItems(
endpoint: string,
diff --git a/src/server/lib/dataforseo/filters.ts b/src/server/lib/dataforseo/filters.ts
new file mode 100644
index 0000000..035707c
--- /dev/null
+++ b/src/server/lib/dataforseo/filters.ts
@@ -0,0 +1,89 @@
+import { AppError } from "@/server/lib/errors";
+import { MAX_DATAFORSEO_FILTER_CONDITIONS } from "@/types/schemas/domain";
+
+/**
+ * Building blocks for DataForSEO `filters` expressions, shared by the
+ * feature-specific builders (domain keywords, backlinks). A "clause" is one
+ * condition tuple like ["field", "ilike", "%term%"] or a nested group.
+ */
+export type FilterClause = unknown[];
+
+export function escapeLikeTerm(term: string): string {
+ return term.replace(/[\\%_]/g, (match) => `\\${match}`);
+}
+
+/** Splits a comma/plus separated terms string into trimmed lowercase terms. */
+export function parseFilterTerms(value: string | undefined): string[] {
+ if (!value) return [];
+ return value
+ .toLowerCase()
+ .split(/[,+]/)
+ .map((term) => term.trim())
+ .filter(Boolean);
+}
+
+export function collectNumericRange(
+ out: FilterClause[],
+ field: string,
+ min: number | undefined,
+ max: number | undefined,
+) {
+ if (typeof min === "number" && Number.isFinite(min)) {
+ out.push([field, ">=", min]);
+ }
+ if (typeof max === "number" && Number.isFinite(max)) {
+ out.push([field, "<=", max]);
+ }
+}
+
+/**
+ * One ilike condition per include term, joined with "or" into a single nested
+ * group (match-any semantics). Returns the group clause plus how many of the
+ * DataForSEO condition budget it consumes.
+ */
+export function buildIncludeOrGroup(
+ field: string,
+ include: string | undefined,
+): { clause: FilterClause; conditionCount: number } | null {
+ const conditions = parseFilterTerms(include).map((term) => [
+ field,
+ "ilike",
+ `%${escapeLikeTerm(term)}%`,
+ ]);
+ if (conditions.length === 0) return null;
+ const first = conditions[0];
+ if (conditions.length === 1 && first) {
+ return { clause: first, conditionCount: 1 };
+ }
+ return {
+ clause: joinClauses(conditions, "or"),
+ conditionCount: conditions.length,
+ };
+}
+
+/**
+ * DataForSEO accepts up to 8 filter conditions per request. The clients
+ * surface the same condition count and disable Apply when over budget, so
+ * reaching the cap here indicates a misbehaving client — we throw rather
+ * than silently truncate.
+ */
+export function assertFilterConditionBudget(conditionCount: number): void {
+ if (conditionCount > MAX_DATAFORSEO_FILTER_CONDITIONS) {
+ throw new AppError(
+ "VALIDATION_ERROR",
+ `Too many filter conditions (${conditionCount} of ${MAX_DATAFORSEO_FILTER_CONDITIONS} max).`,
+ );
+ }
+}
+
+export function joinClauses(
+ clauses: FilterClause[],
+ operator: "and" | "or",
+): unknown[] {
+ const expressions: unknown[] = [];
+ for (const clause of clauses) {
+ if (expressions.length > 0) expressions.push(operator);
+ expressions.push(clause);
+ }
+ return expressions;
+}
diff --git a/src/server/mcp/tools/get-backlinks-overview.ts b/src/server/mcp/tools/get-backlinks-overview.ts
index 35ab54b..02df2f5 100644
--- a/src/server/mcp/tools/get-backlinks-overview.ts
+++ b/src/server/mcp/tools/get-backlinks-overview.ts
@@ -57,24 +57,28 @@ export const getBacklinksOverviewTool = {
const lookup = { target: args.target, scope: args.scope };
const spamOptions = { hideSpam: args.hideSpam ?? true };
const [overview, refDomains] = await Promise.all([
- BacklinksService.profileOverview(lookup, context.billing, spamOptions),
- BacklinksService.profileReferringDomains(
- lookup,
+ BacklinksService.profileOverview(lookup, context.billing),
+ BacklinksService.profileReferringDomainsPage(
+ {
+ ...lookup,
+ page: 1,
+ pageSize: 100,
+ sortField: "backlinks",
+ sortOrder: "desc",
+ filters: {},
+ },
context.billing,
spamOptions,
),
]);
const topDomains = refDomains.rows ?? [];
- const overviewRecord =
- overview && typeof overview === "object"
- ? (overview as Record)
- : {};
+ const summary = overview.overview.summary;
const text = [
`Backlinks profile for ${args.target} (${args.scope ?? "domain"}):`,
- `- backlinks: ${formatMetric(overviewRecord.backlinks)}`,
- `- referring domains: ${formatMetric(overviewRecord.referring_domains)}`,
- `- referring pages: ${formatMetric(overviewRecord.referring_pages)}`,
- `- rank: ${formatMetric(overviewRecord.rank)}`,
+ `- backlinks: ${formatMetric(summary.backlinks)}`,
+ `- referring domains: ${formatMetric(summary.referringDomains)}`,
+ `- referring pages: ${formatMetric(summary.referringPages)}`,
+ `- rank: ${formatMetric(summary.rank)}`,
"",
`Top referring domains (${Math.min(topDomains.length, 10)} shown):`,
...topDomains
diff --git a/src/serverFunctions/backlinks.ts b/src/serverFunctions/backlinks.ts
index 5b03535..d732e3c 100644
--- a/src/serverFunctions/backlinks.ts
+++ b/src/serverFunctions/backlinks.ts
@@ -1,7 +1,16 @@
import { createServerFn } from "@tanstack/react-start";
import { BacklinksService } from "@/server/features/backlinks/services/BacklinksService";
import { requireProjectContext } from "@/serverFunctions/middleware";
-import { backlinksOverviewInputSchema } from "@/types/schemas/backlinks";
+import {
+ backlinksOverviewInputSchema,
+ backlinksRowsPageRequestSchema,
+ referringDomainsPageRequestSchema,
+ 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.
+const WEB_SPAM_OPTIONS = { hideSpam: false };
export const getBacklinksOverview = createServerFn({
method: "POST",
@@ -9,49 +18,45 @@ export const getBacklinksOverview = createServerFn({
.middleware(requireProjectContext)
.inputValidator((data: unknown) => backlinksOverviewInputSchema.parse(data))
.handler(async ({ data, context }) => {
- const input = {
- target: data.target,
- scope: data.scope,
- };
- const spamOptions = {
- hideSpam: data.hideSpam,
- spamThreshold: data.spamThreshold,
- };
const profile = await BacklinksService.profileOverview(
- input,
+ {
+ target: data.target,
+ scope: data.scope,
+ },
context,
- spamOptions,
);
return profile.overview;
});
+export const getBacklinksRows = createServerFn({
+ method: "POST",
+})
+ .middleware(requireProjectContext)
+ .inputValidator((data: unknown) => backlinksRowsPageRequestSchema.parse(data))
+ .handler(({ data, context }) =>
+ BacklinksService.profileBacklinksPage(data, context, WEB_SPAM_OPTIONS),
+ );
+
export const getBacklinksReferringDomains = createServerFn({
method: "POST",
})
.middleware(requireProjectContext)
- .inputValidator((data: unknown) => backlinksOverviewInputSchema.parse(data))
- .handler(async ({ data, context }) => {
- const input = {
- target: data.target,
- scope: data.scope,
- };
- const profile = await BacklinksService.profileReferringDomains(
- input,
+ .inputValidator((data: unknown) =>
+ referringDomainsPageRequestSchema.parse(data),
+ )
+ .handler(({ data, context }) =>
+ BacklinksService.profileReferringDomainsPage(
+ data,
context,
- );
- return profile.rows;
- });
+ WEB_SPAM_OPTIONS,
+ ),
+ );
export const getBacklinksTopPages = createServerFn({
method: "POST",
})
.middleware(requireProjectContext)
- .inputValidator((data: unknown) => backlinksOverviewInputSchema.parse(data))
- .handler(async ({ data, context }) => {
- const input = {
- target: data.target,
- scope: data.scope,
- };
- const profile = await BacklinksService.profileTopPages(input, context);
- return profile.rows;
- });
+ .inputValidator((data: unknown) => topPagesPageRequestSchema.parse(data))
+ .handler(({ data, context }) =>
+ BacklinksService.profileTopPagesPage(data, context),
+ );
diff --git a/src/types/schemas/backlinks.ts b/src/types/schemas/backlinks.ts
index daaa059..08be167 100644
--- a/src/types/schemas/backlinks.ts
+++ b/src/types/schemas/backlinks.ts
@@ -40,23 +40,192 @@ export const backlinksProjectSchema = z.object({
projectId: z.string().min(1),
});
-const backlinksSpamFilterSchema = z.object({
- hideSpam: z.boolean().optional(),
- spamThreshold: z.number().int().min(0).max(100).optional(),
+export const backlinksOverviewInputSchema = backlinksLookupSchema.extend({
+ projectId: z.string().min(1),
});
-export const backlinksOverviewInputSchema = backlinksLookupSchema
- .extend({
- projectId: z.string().min(1),
- })
- .merge(backlinksSpamFilterSchema);
+/* ------------------------------------------------------------------ */
+/* Paginated tab requests */
+/* ------------------------------------------------------------------ */
+
+export const BACKLINKS_PAGE_SIZES = [50, 100, 200] as const;
+export const DEFAULT_BACKLINKS_PAGE_SIZE = 100;
+
+const optionalNumber = z
+ .union([
+ z.number(),
+ z.string().transform((value, ctx) => {
+ const trimmed = value.trim();
+ if (trimmed === "") return undefined;
+ const parsed = Number(trimmed);
+ if (!Number.isFinite(parsed)) {
+ ctx.addIssue({ code: "custom", message: "Invalid number" });
+ return z.NEVER;
+ }
+ return parsed;
+ }),
+ ])
+ .optional();
+
+export const backlinksRowsFiltersSchema = z.object({
+ include: z.string().optional(),
+ exclude: z.string().optional(),
+ minDomainRank: optionalNumber,
+ maxDomainRank: optionalNumber,
+ minLinkAuthority: optionalNumber,
+ maxLinkAuthority: optionalNumber,
+ minSpamScore: optionalNumber,
+ maxSpamScore: optionalNumber,
+ linkType: z.enum(["dofollow", "nofollow"]).optional(),
+ hideLost: z.boolean().optional(),
+ hideBroken: z.boolean().optional(),
+ /** Exact-match on the linking domain; used to expand one domain's links. */
+ domainFrom: z.string().max(255).optional(),
+});
+
+/**
+ * DataForSEO result grouping for the backlinks list: `one_per_domain` returns
+ * each referring domain's strongest link (the default, denoised view);
+ * `as_is` returns every individual backlink.
+ */
+const backlinksRowsModeSchema = z.enum(["one_per_domain", "as_is"]);
+
+export const referringDomainsFiltersSchema = z.object({
+ include: z.string().optional(),
+ exclude: z.string().optional(),
+ minBacklinks: optionalNumber,
+ maxBacklinks: optionalNumber,
+ minRank: optionalNumber,
+ maxRank: optionalNumber,
+ minSpamScore: optionalNumber,
+ maxSpamScore: optionalNumber,
+});
+
+export const topPagesFiltersSchema = z.object({
+ include: z.string().optional(),
+ exclude: z.string().optional(),
+ minBacklinks: optionalNumber,
+ maxBacklinks: optionalNumber,
+ minReferringDomains: optionalNumber,
+ maxReferringDomains: optionalNumber,
+ minRank: optionalNumber,
+ maxRank: optionalNumber,
+});
+
+export const backlinksSortOrderSchema = z.enum(["asc", "desc"]);
+// Sort field names double as table column ids on the client; the server maps
+// them to DataForSEO field names.
+export const backlinksRowsSortFieldSchema = z.enum([
+ "rank",
+ "domainRank",
+ "spamScore",
+ "firstSeen",
+]);
+export const referringDomainsSortFieldSchema = z.enum([
+ "domain",
+ "backlinks",
+ "referringPages",
+ "rank",
+ "spamScore",
+ "firstSeen",
+ "brokenBacklinks",
+]);
+export const topPagesSortFieldSchema = z.enum([
+ "backlinks",
+ "referringDomains",
+ "rank",
+ "brokenBacklinks",
+]);
+
+/** Single source for each tab's default sort, shared by the request-schema
+ * defaults and the client's header indicators / query fallbacks. */
+export const BACKLINKS_DEFAULT_SORT = {
+ backlinks: { field: "rank", order: "desc" },
+ domains: { field: "backlinks", order: "desc" },
+ pages: { field: "backlinks", order: "desc" },
+} as const satisfies Record<
+ z.infer,
+ { field: string; order: z.infer }
+>;
+
+const backlinksPageRequestBase = backlinksLookupSchema.extend({
+ projectId: z.string().min(1),
+ page: z.number().int().positive().default(1),
+ pageSize: z
+ .number()
+ .int()
+ .refine((value) =>
+ (BACKLINKS_PAGE_SIZES as readonly number[]).includes(value),
+ )
+ .default(DEFAULT_BACKLINKS_PAGE_SIZE),
+ sortOrder: backlinksSortOrderSchema.default("desc"),
+});
+
+export const backlinksRowsPageRequestSchema = backlinksPageRequestBase.extend({
+ sortField: backlinksRowsSortFieldSchema.default(
+ BACKLINKS_DEFAULT_SORT.backlinks.field,
+ ),
+ filters: backlinksRowsFiltersSchema.default({}),
+ mode: backlinksRowsModeSchema.default("one_per_domain"),
+});
+
+export const referringDomainsPageRequestSchema =
+ backlinksPageRequestBase.extend({
+ sortField: referringDomainsSortFieldSchema.default(
+ BACKLINKS_DEFAULT_SORT.domains.field,
+ ),
+ filters: referringDomainsFiltersSchema.default({}),
+ });
+
+export const topPagesPageRequestSchema = backlinksPageRequestBase.extend({
+ sortField: topPagesSortFieldSchema.default(
+ BACKLINKS_DEFAULT_SORT.pages.field,
+ ),
+ filters: topPagesFiltersSchema.default({}),
+});
export const backlinksSearchSchema = z.object({
target: z.string().optional(),
scope: backlinksTargetScopeSchema.optional(),
tab: backlinksTabSchema.optional(),
+ page: z.coerce.number().int().positive().optional().catch(undefined),
+ size: z.coerce
+ .number()
+ .int()
+ .refine((value) =>
+ (BACKLINKS_PAGE_SIZES as readonly number[]).includes(value),
+ )
+ .optional()
+ .catch(undefined),
+ // Sort column id for the active tab; validated against the tab's sort-field
+ // enum when building the request, so a mismatched value falls back to the
+ // tab's default sort.
+ sort: z.string().optional().catch(undefined),
+ order: backlinksSortOrderSchema.optional().catch(undefined),
+ // Backlinks tab only: "all" shows every link; default is one per domain.
+ view: z.literal("all").optional().catch(undefined),
});
export type BacklinksLookupInput = z.infer;
export type BacklinksTab = z.infer;
export type BacklinksTargetScope = z.infer;
+export type BacklinksSortOrder = z.infer;
+export type BacklinksRowsSortField = z.infer<
+ typeof backlinksRowsSortFieldSchema
+>;
+export type ReferringDomainsSortField = z.infer<
+ typeof referringDomainsSortFieldSchema
+>;
+export type TopPagesSortField = z.infer;
+export type BacklinksRowsFilters = z.infer;
+export type ReferringDomainsFilters = z.infer<
+ typeof referringDomainsFiltersSchema
+>;
+export type TopPagesFilters = z.infer;
+export type BacklinksRowsPageInput = z.infer<
+ typeof backlinksRowsPageRequestSchema
+>;
+export type ReferringDomainsPageInput = z.infer<
+ typeof referringDomainsPageRequestSchema
+>;
+export type TopPagesPageInput = z.infer;