Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import { z } from "zod";
import {
RESEARCH_SCOPES,
RESEARCH_SCOPE_PARAM_DESCRIPTION,
type ResearchScope,
} from "@/shared/researchScope";
export const backlinksTabSchema = z.enum(["backlinks", "domains", "pages"]);
/**
* Backlinks uses the shared research scopes. DataForSEO has no prefix
* targeting, so subfolder rides on url_to/url prefix filters: backlink rows
* and top pages are provider-filtered, summary counts come from filtered
* backlink totals, and rank/trends/referring-domains stay unavailable.
*/
export type BacklinksTargetScope = ResearchScope;
/**
* Scope as it arrives from persisted or external state (URLs, MCP clients).
* "page" is the pre-research-scope name for exact_url and is still accepted.
*/
export const backlinksScopeWithLegacySchema = z.enum([
...RESEARCH_SCOPES,
"page",
]);
export type BacklinksScopeWithLegacy = z.infer<
typeof backlinksScopeWithLegacySchema
>;
export function resolveBacklinksScope(
scope: BacklinksScopeWithLegacy,
): ResearchScope {
return scope === "page" ? "exact_url" : scope;
}
export const backlinksScopeParamSchema =
backlinksScopeWithLegacySchema.transform(resolveBacklinksScope);
/** 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.`;
export const DEFAULT_BACKLINKS_SPAM_THRESHOLD = 40;
export type BacklinksSpamFilterOptions = {
hideSpam?: boolean;
};
export const backlinksLookupSchema = z.object({
target: z.string().min(1, "Target is required").max(2048),
scope: backlinksScopeParamSchema.optional(),
});
export const backlinksOverviewInputSchema = backlinksLookupSchema.extend({
projectId: z.string().min(1),
});
/* ------------------------------------------------------------------ */
/* Paginated tab requests */
/* ------------------------------------------------------------------ */
export const BACKLINKS_PAGE_SIZES = [50, 100, 200] as const;
export const DEFAULT_BACKLINKS_PAGE_SIZE = 50;
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.
*/
export 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: "firstSeen", order: "desc" },
domains: { field: "backlinks", order: "desc" },
pages: { field: "backlinks", order: "desc" },
} as const satisfies Record<
z.infer<typeof backlinksTabSchema>,
{ field: string; order: z.infer<typeof backlinksSortOrderSchema> }
>;
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({
hideSpam: z.boolean().optional(),
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({
includeSpam: z.boolean().optional().catch(undefined),
target: z.string().optional(),
scope: backlinksScopeParamSchema.optional().catch(undefined),
tab: backlinksTabSchema.optional().catch(undefined),
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<typeof backlinksLookupSchema>;
export type BacklinksTab = z.infer<typeof backlinksTabSchema>;
export type BacklinksSortOrder = z.infer<typeof backlinksSortOrderSchema>;
export type BacklinksRowsSortField = z.infer<
typeof backlinksRowsSortFieldSchema
>;
export type ReferringDomainsSortField = z.infer<
typeof referringDomainsSortFieldSchema
>;
export type TopPagesSortField = z.infer<typeof topPagesSortFieldSchema>;
export type BacklinksRowsFilters = z.infer<typeof backlinksRowsFiltersSchema>;
export type ReferringDomainsFilters = z.infer<
typeof referringDomainsFiltersSchema
>;
export type TopPagesFilters = z.infer<typeof topPagesFiltersSchema>;
export type BacklinksRowsPageInput = z.infer<
typeof backlinksRowsPageRequestSchema
>;
export type ReferringDomainsPageInput = z.infer<
typeof referringDomainsPageRequestSchema
>;
export type TopPagesPageInput = z.infer<typeof topPagesPageRequestSchema>;