@nuxtseo/protocol 0.4.1 → 0.5.1

package/dist/v1/backlinks.js

@@ -361,6 +361,35 @@ export const liveBacklinksQuerySchema = schema.strictObject({
     limit: schema.coerce.number().int().min(1).max(1000).default(100),
 });
 const nullableCount = schema.number().nullable();
+/**
+ * A Link Spam Network: referring domains that each place one generated anchor
+ * with the Site's host written into it, one link per domain. It is read from
+ * the retained Backlinks rows, never from `spamScore`. Google ignores most
+ * links like these, so the summary counts them apart from the profile.
+ */
+export const linkSpamNetworkSchema = defineResponseObject({
+    /** Stable for one anchor template on one Site. */
+    id: schema.string().min(1),
+    /** The anchor as the provider reported it, with the Site's host in it. */
+    anchor: schema.string().min(1),
+    referringDomains: schema.number().int().nonnegative(),
+    backlinks: schema.number().int().nonnegative(),
+    /** When the provider first saw the anchor. */
+    firstSeen: schema.string().nullable(),
+    /** When the newest sampled member domain was first seen. */
+    latestSeen: schema.string().nullable(),
+    /** The linking page path every sampled member shares, or null when they differ. */
+    linkingPath: schema.string().nullable(),
+    /** Paths on the Site that the sampled members link to, most linked first. */
+    targetPaths: schema.array(schema.string()),
+    /** Other Sites whose anchors carry the same template. */
+    otherSites: schema.number().int().nonnegative(),
+});
+/** The profile totals with every Link Spam Network removed. */
+const profileWithoutNetworksSchema = defineResponseObject({
+    referringDomains: schema.number().int().nonnegative(),
+    backlinks: schema.number().int().nonnegative(),
+});
 export const backlinksSummaryDataSchema = defineResponseObject({
     target: schema.string().min(1),
     rank: nullableCount,
@@ -375,6 +404,21 @@ export const backlinksSummaryDataSchema = defineResponseObject({
     referringIps: nullableCount,
     referringSubnets: nullableCount,
     referringPages: nullableCount,
+    /**
+     * The Site's Link Spam Networks, largest first. Empty for most Sites. The
+     * counts above still include them.
+     *
+     * A producer must send it and `withoutLinkSpamNetworks`. A client treats
+     * both as optional, because a client newer than the deployed server reads
+     * answers that predate the fields.
+     */
+    linkSpamNetworks: schema.array(linkSpamNetworkSchema.producer),
+    /**
+     * `referringDomains` and `backlinks` without the networks. Null when the
+     * Site has no network, or when the provider returned no total to subtract
+     * from.
+     */
+    withoutLinkSpamNetworks: profileWithoutNetworksSchema.producer.nullable(),
     evidence: liveBacklinksEvidenceProducerSchema,
 }, {
     target: schema.string().min(1),
@@ -390,6 +434,8 @@ export const backlinksSummaryDataSchema = defineResponseObject({
     referringIps: nullableCount,
     referringSubnets: nullableCount,
     referringPages: nullableCount,
+    linkSpamNetworks: schema.array(linkSpamNetworkSchema.client).optional(),
+    withoutLinkSpamNetworks: profileWithoutNetworksSchema.client.nullable().optional(),
     evidence: liveBacklinksEvidenceClientSchema,
 });
 export const backlinksSummaryResponseSchema = defineSuccessEnvelope(backlinksSummaryDataSchema);
@@ -409,7 +455,7 @@ export const backlinksSummaryOperation = defineOperation({
     lifecycle: { introduced: '1.2.0' },
     docs: {
         summary: 'Get Backlinks summary',
-        description: 'Returns whole-domain inbound link totals for the Site: backlinks, referring domains, broken counts, and the domain rank. Cached reads consume no units.',
+        description: 'Returns whole-domain inbound link totals for the Site: backlinks, referring domains, broken counts, and the domain rank. It also lists the link spam networks in the retained rows, and the totals without them. Cached reads consume no units.',
         tags: ['Research'],
         examples: [{
                 request: { params: { siteId: 'site_01JXYZ' } },
@@ -430,6 +476,18 @@ export const backlinksSummaryOperation = defineOperation({
                             referringIps: 350,
                             referringSubnets: 322,
                             referringPages: 4800,
+                            linkSpamNetworks: [{
+                                    id: 'lsn_5d1c07a2',
+                                    anchor: 'Premium SEO Link Building Experts Helping example.com Websites Rank Higher',
+                                    referringDomains: 42,
+                                    backlinks: 42,
+                                    firstSeen: '2026-08-02T00:00:00.000Z',
+                                    latestSeen: '2026-09-20T00:00:00.000Z',
+                                    linkingPath: '/dir/organic-visibility-backlinks-86677',
+                                    targetPaths: ['/'],
+                                    otherSites: 201,
+                                }],
+                            withoutLinkSpamNetworks: { referringDomains: 370, backlinks: 5078 },
                             evidence: { _tag: 'live', provider: 'dataforseo', spend: { key: 'dataforseo', units: 1 } },
                         },
                         meta: { requestId: 'req_01JXYZ', version: '1.0' },
@@ -450,6 +508,14 @@ export const referringDomainSchema = defineResponseObject({
     lostDate: schema.string().nullable(),
     /** 90-day referral sessions from this domain, or null when no Web Analytics property is linked. */
     sessions: nullableCount,
+    /**
+     * The id of the Link Spam Network this domain is a known member of, as in
+     * the summary's `linkSpamNetworks`. `null` means not known to be in one,
+     * never verified clean: membership is known only for the domains the
+     * retained rows sampled or the Timeline recorded. A producer must send it;
+     * a client treats it as optional, because older servers do not.
+     */
+    linkSpamNetworkId: schema.string().min(1).nullable(),
 }, {
     domain: schema.string().min(1),
     rank: nullableCount,
@@ -461,6 +527,7 @@ export const referringDomainSchema = defineResponseObject({
     firstSeen: schema.string().nullable(),
     lostDate: schema.string().nullable(),
     sessions: nullableCount,
+    linkSpamNetworkId: schema.string().min(1).nullable().optional(),
 });
 export const referringDomainsDataSchema = defineResponseObject({
     target: schema.string().min(1),
@@ -492,7 +559,7 @@ export const referringDomainsOperation = defineOperation({
     lifecycle: { introduced: '1.2.0' },
     docs: {
         summary: 'List referring domains',
-        description: 'Returns the domains that link to the Site, highest authority first, with spam score and broken-link counts. When a Web Analytics property is linked, each row also carries its 90-day referral sessions, so a link that sends nobody is visible. Cached reads consume no units.',
+        description: 'Returns the domains that link to the Site, highest authority first, with spam score and broken-link counts. When a Web Analytics property is linked, each row also carries its 90-day referral sessions, so a link that sends nobody is visible. A row that is a known member of a link spam network carries its id. Cached reads consume no units.',
         tags: ['Research'],
         examples: [{
                 request: { params: { siteId: 'site_01JXYZ' }, query: { limit: 100 } },
@@ -512,6 +579,7 @@ export const referringDomainsOperation = defineOperation({
                                     firstSeen: '2026-02-09 20:43:50 +00:00',
                                     lostDate: null,
                                     sessions: 143,
+                                    linkSpamNetworkId: null,
                                 }],
                             total: 1,
                             limit: 100,
@@ -533,6 +601,14 @@ export const backlinkAnchorSchema = defineResponseObject({
     spamScore: nullableCount,
     firstSeen: schema.string().nullable(),
     lostDate: schema.string().nullable(),
+    /**
+     * The id of the Link Spam Network whose generated sentence this anchor is,
+     * as in the summary's `linkSpamNetworks`. Exact, because the anchor is the
+     * evidence. `null` means not known to be in one, never verified clean. A
+     * producer must send it; a client treats it as optional, because older
+     * servers do not.
+     */
+    linkSpamNetworkId: schema.string().min(1).nullable(),
 }, {
     anchor: schema.string(),
     rank: nullableCount,
@@ -543,6 +619,7 @@ export const backlinkAnchorSchema = defineResponseObject({
     spamScore: nullableCount,
     firstSeen: schema.string().nullable(),
     lostDate: schema.string().nullable(),
+    linkSpamNetworkId: schema.string().min(1).nullable().optional(),
 });
 export const backlinkAnchorsDataSchema = defineResponseObject({
     target: schema.string().min(1),
@@ -574,7 +651,7 @@ export const backlinkAnchorsOperation = defineOperation({
     lifecycle: { introduced: '1.2.0' },
     docs: {
         summary: 'List Backlink anchors',
-        description: 'Returns the anchor text distribution of the Site inbound links, most linked first. Use it to find over-optimised or off-brand anchors. Cached reads consume no units.',
+        description: 'Returns the anchor text distribution of the Site inbound links, most linked first. Use it to find over-optimised or off-brand anchors. An anchor that is the generated sentence of a link spam network carries its id. Cached reads consume no units.',
         tags: ['Research'],
         examples: [{
                 request: { params: { siteId: 'site_01JXYZ' }, query: { limit: 100 } },
@@ -593,6 +670,7 @@ export const backlinkAnchorsOperation = defineOperation({
                                     spamScore: 3,
                                     firstSeen: '2026-01-04 11:02:11 +00:00',
                                     lostDate: null,
+                                    linkSpamNetworkId: null,
                                 }],
                             total: 1,
                             limit: 100,