@nuxtseo/protocol 0.1.0

package/dist/v1/backlinks.js

@@ -0,0 +1,239 @@
+import { z as schema } from 'zod';
+import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
+export const backlinksSiteParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+});
+export const backlinksPageQuerySchema = schema.strictObject({
+    limit: schema.coerce.number().int().min(1).max(200).default(100),
+    offset: schema.coerce.number().int().min(0).default(0),
+});
+/**
+ * One inbound link whose destination is broken. `destinationStatus` is the
+ * status the destination answered with when the provider last checked, so a
+ * consumer can separate a 404 from a 5xx without refetching.
+ */
+export const recoverableBacklinkSchema = defineResponseObject({
+    id: schema.string().min(1),
+    destinationUrl: schema.string().min(1),
+    referringUrl: schema.string().min(1),
+    referringDomain: schema.string().min(1),
+    anchor: schema.string().nullable(),
+    destinationStatus: schema.number().int().nullable(),
+    domainRank: schema.number().int().nullable(),
+    pageRank: schema.number().int().nullable(),
+    dofollow: schema.boolean().nullable(),
+    firstSeenAt: schema.string().datetime().nullable(),
+    lastSeenAt: schema.string().datetime().nullable(),
+}, {
+    id: schema.string().min(1),
+    destinationUrl: schema.string().min(1),
+    referringUrl: schema.string().min(1),
+    referringDomain: schema.string().min(1),
+    anchor: schema.string().nullable(),
+    destinationStatus: schema.number().int().nullable(),
+    domainRank: schema.number().int().nullable(),
+    pageRank: schema.number().int().nullable(),
+    dofollow: schema.boolean().nullable(),
+    firstSeenAt: schema.string().datetime().nullable(),
+    lastSeenAt: schema.string().datetime().nullable(),
+});
+export const recoverableBacklinksDataSchema = defineResponseObject({
+    items: schema.array(recoverableBacklinkSchema.producer),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+    offset: schema.number().int().nonnegative(),
+}, {
+    items: schema.array(recoverableBacklinkSchema.client),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+    offset: schema.number().int().nonnegative(),
+});
+export const recoverableBacklinksResponseSchema = defineSuccessEnvelope(recoverableBacklinksDataSchema);
+export const recoverableBacklinksOperation = defineOperation({
+    id: 'backlinks.recoverable',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/backlinks/recoverable',
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'primary' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['research:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: { params: backlinksSiteParamsSchema, query: backlinksPageQuerySchema, headers: null, body: null },
+    responses: { 200: recoverableBacklinksResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'not_found',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: {
+        reads: [{ type: 'site.research', idFrom: 'params.siteId' }],
+        changes: [],
+    },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.1.0' },
+    docs: {
+        summary: 'List recoverable Backlinks',
+        description: 'Returns retained inbound links whose destination is broken, ranked by referring domain authority. Each item carries the referring URL and the destination URL, so a redirect can be written without a crawl. It never starts provider work and does not consume metered units.',
+        tags: ['Research'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { limit: 100, offset: 0 } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            items: [{
+                                    id: 'bl_01JXYZ',
+                                    destinationUrl: 'https://example.com/docs/utils',
+                                    referringUrl: 'https://news.example/posts/seo',
+                                    referringDomain: 'news.example',
+                                    anchor: 'Read the full documentation',
+                                    destinationStatus: 404,
+                                    domainRank: 529,
+                                    pageRank: 55,
+                                    dofollow: true,
+                                    firstSeenAt: '2026-02-09T20:43:50.000Z',
+                                    lastSeenAt: '2026-07-17T04:40:07.000Z',
+                                }],
+                            total: 1,
+                            limit: 100,
+                            offset: 0,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const backlinksV1Registry = defineRegistry({
+    feature: 'backlinks',
+    operations: {
+        recoverable: recoverableBacklinksOperation,
+    },
+});
+export const mentionsQuerySchema = schema.strictObject({
+    limit: schema.coerce.number().int().min(1).max(200).default(100),
+    includeFiltered: schema.enum(['0', '1']).default('0'),
+});
+export const mentionSchema = defineResponseObject({
+    id: schema.string().min(1),
+    source: schema.string().min(1),
+    url: schema.string().min(1),
+    domain: schema.string().min(1),
+    title: schema.string().nullable(),
+    snippet: schema.string().nullable(),
+    author: schema.string().nullable(),
+    authorHandle: schema.string().nullable(),
+    engagement: schema.number().int().nullable(),
+    sentiment: schema.string().nullable(),
+    domainRank: schema.number().int().nullable(),
+    publishedAt: schema.string().datetime().nullable(),
+}, {
+    id: schema.string().min(1),
+    source: schema.string().min(1),
+    url: schema.string().min(1),
+    domain: schema.string().min(1),
+    title: schema.string().nullable(),
+    snippet: schema.string().nullable(),
+    author: schema.string().nullable(),
+    authorHandle: schema.string().nullable(),
+    engagement: schema.number().int().nullable(),
+    sentiment: schema.string().nullable(),
+    domainRank: schema.number().int().nullable(),
+    publishedAt: schema.string().datetime().nullable(),
+});
+export const mentionsDataSchema = defineResponseObject({
+    items: schema.array(mentionSchema.producer),
+    limit: schema.number().int().positive(),
+}, {
+    items: schema.array(mentionSchema.client),
+    limit: schema.number().int().positive(),
+});
+export const mentionsResponseSchema = defineSuccessEnvelope(mentionsDataSchema);
+export const mentionsListOperation = defineOperation({
+    id: 'mentions.list',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/mentions',
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'primary' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['research:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: { params: backlinksSiteParamsSchema, query: mentionsQuerySchema, headers: null, body: null },
+    responses: { 200: mentionsResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'not_found',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: {
+        reads: [{ type: 'site.research', idFrom: 'params.siteId' }],
+        changes: [],
+    },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.1.0' },
+    docs: {
+        summary: 'List Mentions',
+        description: 'Returns retained pages and posts that name the Site without linking to it, newest first. Dismissed and lost Mentions are excluded. Pass includeFiltered=1 to keep the ones AI triage marked a false positive. It never starts provider work and does not consume metered units.',
+        tags: ['Research'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { limit: 100, includeFiltered: '0' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            items: [{
+                                    id: 'mn_01JXYZ',
+                                    source: 'hackernews',
+                                    url: 'https://news.ycombinator.com/item?id=1',
+                                    domain: 'news.ycombinator.com',
+                                    title: 'Show HN: a sitemap module',
+                                    snippet: 'We moved to example.com last week',
+                                    author: 'Ada Lovelace',
+                                    authorHandle: 'ada',
+                                    engagement: 142,
+                                    sentiment: 'positive',
+                                    domainRank: 812,
+                                    publishedAt: '2026-08-01T09:12:00.000Z',
+                                }],
+                            limit: 100,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const mentionsV1Registry = defineRegistry({
+    feature: 'mentions',
+    operations: {
+        list: mentionsListOperation,
+    },
+});