@nuxtseo/protocol 0.1.5 → 0.2.0

package/dist/v1/backlinks.js

@@ -118,12 +118,6 @@ export const recoverableBacklinksOperation = defineOperation({
             }],
     },
 });
-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: publicV1BooleanFlag(false),
@@ -237,3 +231,418 @@ export const mentionsV1Registry = defineRegistry({
         list: mentionsListOperation,
     },
 });
+// ---------------------------------------------------------------------------
+// Live Backlinks (DataForSEO). These four operations reproduce the non-stored
+// modes of the `backlinks` MCP tool. Each one may start provider work, so each
+// carries the Growth entitlement and the `dataforseo` meter, and each returns
+// `evidence` saying whether the answer came from cache or from a live call.
+// `backlinks.recoverable` above stays free: it reads retained rows only.
+// ---------------------------------------------------------------------------
+const liveBacklinksSemantics = {
+    kind: 'query',
+    sideEffects: 'none',
+    retry: 'idempotent',
+    readConsistency: 'primary',
+};
+const liveBacklinksAuth = {
+    credentials: ['session', 'api_token'],
+    scopes: ['research:read'],
+    minimumRole: 'viewer',
+    ownership: 'site',
+};
+const liveBacklinksErrors = [
+    'invalid_request',
+    'unauthorized',
+    'auth_expired',
+    'forbidden',
+    'not_found',
+    'entitlement_required',
+    'quota_exhausted',
+    'provider_unavailable',
+    'conflict',
+    'rate_limited',
+    'contract_violation',
+    'internal_error',
+];
+const liveBacklinksPolicy = {
+    rate: publicV1StandardRatePolicy,
+    idempotency: { _tag: 'none' },
+    entitlement: 'growth',
+    meter: { key: 'dataforseo', units: 1, charge: 'live-only' },
+};
+const liveBacklinksEvidenceProducerSchema = schema.discriminatedUnion('_tag', [
+    schema.strictObject({
+        _tag: schema.literal('no-provider'),
+        provider: schema.null(),
+        spend: schema.strictObject({ key: schema.literal('dataforseo'), units: schema.literal(0) }),
+    }),
+    schema.strictObject({
+        _tag: schema.literal('cache'),
+        provider: schema.literal('dataforseo'),
+        spend: schema.strictObject({ key: schema.literal('dataforseo'), units: schema.literal(0) }),
+    }),
+    schema.strictObject({
+        _tag: schema.literal('live'),
+        provider: schema.literal('dataforseo'),
+        spend: schema.strictObject({ key: schema.literal('dataforseo'), units: schema.literal(1) }),
+    }),
+]);
+const liveBacklinksEvidenceClientSchema = schema.discriminatedUnion('_tag', [
+    schema.looseObject({
+        _tag: schema.literal('no-provider'),
+        provider: schema.null(),
+        spend: schema.looseObject({ key: schema.literal('dataforseo'), units: schema.literal(0) }),
+    }),
+    schema.looseObject({
+        _tag: schema.literal('cache'),
+        provider: schema.literal('dataforseo'),
+        spend: schema.looseObject({ key: schema.literal('dataforseo'), units: schema.literal(0) }),
+    }),
+    schema.looseObject({
+        _tag: schema.literal('live'),
+        provider: schema.literal('dataforseo'),
+        spend: schema.looseObject({ key: schema.literal('dataforseo'), units: schema.literal(1) }),
+    }),
+]);
+/** The target a live Backlinks read resolves to: the Site's own bare domain. */
+export const liveBacklinksQuerySchema = schema.strictObject({
+    limit: schema.coerce.number().int().min(1).max(1000).default(100),
+});
+const nullableCount = schema.number().nullable();
+export const backlinksSummaryDataSchema = defineResponseObject({
+    target: schema.string().min(1),
+    rank: nullableCount,
+    backlinks: nullableCount,
+    brokenBacklinks: nullableCount,
+    brokenPages: nullableCount,
+    crawledPages: nullableCount,
+    spamScore: nullableCount,
+    referringDomains: nullableCount,
+    referringDomainsNofollow: nullableCount,
+    referringMainDomains: nullableCount,
+    referringIps: nullableCount,
+    referringSubnets: nullableCount,
+    referringPages: nullableCount,
+    evidence: liveBacklinksEvidenceProducerSchema,
+}, {
+    target: schema.string().min(1),
+    rank: nullableCount,
+    backlinks: nullableCount,
+    brokenBacklinks: nullableCount,
+    brokenPages: nullableCount,
+    crawledPages: nullableCount,
+    spamScore: nullableCount,
+    referringDomains: nullableCount,
+    referringDomainsNofollow: nullableCount,
+    referringMainDomains: nullableCount,
+    referringIps: nullableCount,
+    referringSubnets: nullableCount,
+    referringPages: nullableCount,
+    evidence: liveBacklinksEvidenceClientSchema,
+});
+export const backlinksSummaryResponseSchema = defineSuccessEnvelope(backlinksSummaryDataSchema);
+export const backlinksSummaryOperation = defineOperation({
+    id: 'backlinks.summary',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/backlinks/summary',
+    visibility: 'public',
+    semantics: liveBacklinksSemantics,
+    auth: liveBacklinksAuth,
+    request: { params: backlinksSiteParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: backlinksSummaryResponseSchema },
+    errors: liveBacklinksErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.research', idFrom: 'params.siteId' }], changes: [] },
+    policy: liveBacklinksPolicy,
+    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.',
+        tags: ['Research'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            target: 'example.com',
+                            rank: 214,
+                            backlinks: 5120,
+                            brokenBacklinks: 34,
+                            brokenPages: 7,
+                            crawledPages: 890,
+                            spamScore: 4,
+                            referringDomains: 412,
+                            referringDomainsNofollow: 88,
+                            referringMainDomains: 388,
+                            referringIps: 350,
+                            referringSubnets: 322,
+                            referringPages: 4800,
+                            evidence: { _tag: 'live', provider: 'dataforseo', spend: { key: 'dataforseo', units: 1 } },
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const referringDomainSchema = defineResponseObject({
+    domain: schema.string().min(1),
+    rank: nullableCount,
+    backlinks: nullableCount,
+    brokenBacklinks: nullableCount,
+    brokenPages: nullableCount,
+    referringPages: nullableCount,
+    spamScore: nullableCount,
+    firstSeen: schema.string().nullable(),
+    lostDate: schema.string().nullable(),
+    /** 90-day referral sessions from this domain, or null when no Web Analytics property is linked. */
+    sessions: nullableCount,
+}, {
+    domain: schema.string().min(1),
+    rank: nullableCount,
+    backlinks: nullableCount,
+    brokenBacklinks: nullableCount,
+    brokenPages: nullableCount,
+    referringPages: nullableCount,
+    spamScore: nullableCount,
+    firstSeen: schema.string().nullable(),
+    lostDate: schema.string().nullable(),
+    sessions: nullableCount,
+});
+export const referringDomainsDataSchema = defineResponseObject({
+    target: schema.string().min(1),
+    items: schema.array(referringDomainSchema.producer),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+    evidence: liveBacklinksEvidenceProducerSchema,
+}, {
+    target: schema.string().min(1),
+    items: schema.array(referringDomainSchema.client),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+    evidence: liveBacklinksEvidenceClientSchema,
+});
+export const referringDomainsResponseSchema = defineSuccessEnvelope(referringDomainsDataSchema);
+export const referringDomainsOperation = defineOperation({
+    id: 'backlinks.referring.domains',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/backlinks/referring-domains',
+    visibility: 'public',
+    semantics: liveBacklinksSemantics,
+    auth: liveBacklinksAuth,
+    request: { params: backlinksSiteParamsSchema, query: liveBacklinksQuerySchema, headers: null, body: null },
+    responses: { 200: referringDomainsResponseSchema },
+    errors: liveBacklinksErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.research', idFrom: 'params.siteId' }], changes: [] },
+    policy: liveBacklinksPolicy,
+    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.',
+        tags: ['Research'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { limit: 100 } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            target: 'example.com',
+                            items: [{
+                                    domain: 'news.example',
+                                    rank: 529,
+                                    backlinks: 12,
+                                    brokenBacklinks: 0,
+                                    brokenPages: 0,
+                                    referringPages: 9,
+                                    spamScore: 2,
+                                    firstSeen: '2026-02-09 20:43:50 +00:00',
+                                    lostDate: null,
+                                    sessions: 143,
+                                }],
+                            total: 1,
+                            limit: 100,
+                            evidence: { _tag: 'cache', provider: 'dataforseo', spend: { key: 'dataforseo', units: 0 } },
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const backlinkAnchorSchema = defineResponseObject({
+    anchor: schema.string(),
+    rank: nullableCount,
+    backlinks: nullableCount,
+    referringDomains: nullableCount,
+    referringMainDomains: nullableCount,
+    referringPages: nullableCount,
+    spamScore: nullableCount,
+    firstSeen: schema.string().nullable(),
+    lostDate: schema.string().nullable(),
+}, {
+    anchor: schema.string(),
+    rank: nullableCount,
+    backlinks: nullableCount,
+    referringDomains: nullableCount,
+    referringMainDomains: nullableCount,
+    referringPages: nullableCount,
+    spamScore: nullableCount,
+    firstSeen: schema.string().nullable(),
+    lostDate: schema.string().nullable(),
+});
+export const backlinkAnchorsDataSchema = defineResponseObject({
+    target: schema.string().min(1),
+    items: schema.array(backlinkAnchorSchema.producer),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+    evidence: liveBacklinksEvidenceProducerSchema,
+}, {
+    target: schema.string().min(1),
+    items: schema.array(backlinkAnchorSchema.client),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+    evidence: liveBacklinksEvidenceClientSchema,
+});
+export const backlinkAnchorsResponseSchema = defineSuccessEnvelope(backlinkAnchorsDataSchema);
+export const backlinkAnchorsOperation = defineOperation({
+    id: 'backlinks.anchors',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/backlinks/anchors',
+    visibility: 'public',
+    semantics: liveBacklinksSemantics,
+    auth: liveBacklinksAuth,
+    request: { params: backlinksSiteParamsSchema, query: liveBacklinksQuerySchema, headers: null, body: null },
+    responses: { 200: backlinkAnchorsResponseSchema },
+    errors: liveBacklinksErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.research', idFrom: 'params.siteId' }], changes: [] },
+    policy: liveBacklinksPolicy,
+    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.',
+        tags: ['Research'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { limit: 100 } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            target: 'example.com',
+                            items: [{
+                                    anchor: 'nuxt seo',
+                                    rank: 480,
+                                    backlinks: 212,
+                                    referringDomains: 64,
+                                    referringMainDomains: 60,
+                                    referringPages: 190,
+                                    spamScore: 3,
+                                    firstSeen: '2026-01-04 11:02:11 +00:00',
+                                    lostDate: null,
+                                }],
+                            total: 1,
+                            limit: 100,
+                            evidence: { _tag: 'cache', provider: 'dataforseo', spend: { key: 'dataforseo', units: 0 } },
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const backlinksHistoryQuerySchema = schema.strictObject({
+    dateFrom: schema.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+});
+export const backlinksHistoryPointSchema = defineResponseObject({
+    date: schema.string().min(1),
+    rank: nullableCount,
+    backlinks: nullableCount,
+    referringDomains: nullableCount,
+    referringMainDomains: nullableCount,
+    referringPages: nullableCount,
+    newReferringDomains: nullableCount,
+    lostReferringDomains: nullableCount,
+    newBacklinks: nullableCount,
+    lostBacklinks: nullableCount,
+}, {
+    date: schema.string().min(1),
+    rank: nullableCount,
+    backlinks: nullableCount,
+    referringDomains: nullableCount,
+    referringMainDomains: nullableCount,
+    referringPages: nullableCount,
+    newReferringDomains: nullableCount,
+    lostReferringDomains: nullableCount,
+    newBacklinks: nullableCount,
+    lostBacklinks: nullableCount,
+});
+export const backlinksHistoryDataSchema = defineResponseObject({
+    target: schema.string().min(1),
+    items: schema.array(backlinksHistoryPointSchema.producer),
+    total: schema.number().int().nonnegative(),
+    evidence: liveBacklinksEvidenceProducerSchema,
+}, {
+    target: schema.string().min(1),
+    items: schema.array(backlinksHistoryPointSchema.client),
+    total: schema.number().int().nonnegative(),
+    evidence: liveBacklinksEvidenceClientSchema,
+});
+export const backlinksHistoryResponseSchema = defineSuccessEnvelope(backlinksHistoryDataSchema);
+export const backlinksHistoryOperation = defineOperation({
+    id: 'backlinks.history',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/backlinks/history',
+    visibility: 'public',
+    semantics: liveBacklinksSemantics,
+    auth: liveBacklinksAuth,
+    request: { params: backlinksSiteParamsSchema, query: backlinksHistoryQuerySchema, headers: null, body: null },
+    responses: { 200: backlinksHistoryResponseSchema },
+    errors: liveBacklinksErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.research', idFrom: 'params.siteId' }], changes: [] },
+    policy: liveBacklinksPolicy,
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Get Backlinks history',
+        description: 'Returns a monthly series of inbound link totals with the domains gained and lost in each month. It defaults to about twelve months; pass dateFrom for a longer window. Cached reads consume no units.',
+        tags: ['Research'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { dateFrom: '2026-01-01' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            target: 'example.com',
+                            items: [{
+                                    date: '2026-08-01',
+                                    rank: 214,
+                                    backlinks: 5120,
+                                    referringDomains: 412,
+                                    referringMainDomains: 388,
+                                    referringPages: 4800,
+                                    newReferringDomains: 18,
+                                    lostReferringDomains: 4,
+                                    newBacklinks: 210,
+                                    lostBacklinks: 62,
+                                }],
+                            total: 1,
+                            evidence: { _tag: 'live', provider: 'dataforseo', spend: { key: 'dataforseo', units: 1 } },
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const backlinksV1Registry = defineRegistry({
+    feature: 'backlinks',
+    operations: {
+        recoverable: recoverableBacklinksOperation,
+        summary: backlinksSummaryOperation,
+        referringDomains: referringDomainsOperation,
+        anchors: backlinkAnchorsOperation,
+        history: backlinksHistoryOperation,
+    },
+});

package/dist/v1/core.d.ts

@@ -20,7 +20,7 @@ export declare const publicV1StandardRatePolicy: {
 export declare const PUBLIC_V1_FEATURES: readonly ['account', 'actions', 'analytics', 'audit', 'backlinks', 'content', 'mentions', 'page', 'research', 'sites', 'timeline'];
 export declare const PUBLIC_V1_METHODS: readonly ['DELETE', 'GET', 'PATCH', 'POST'];
 export declare const PUBLIC_V1_CREDENTIALS: readonly ['api_token', 'session'];
-export declare const PUBLIC_V1_SCOPES: readonly ['account:read', 'actions:read', 'actions:write', 'analytics:read', 'audit:read', 'content:read', 'content:write', 'page:read', 'page:write', 'research:read', 'research:write', 'sites:read', 'sites:write', 'timeline:read'];
+export declare const PUBLIC_V1_SCOPES: readonly ['account:read', 'actions:read', 'actions:write', 'analytics:read', 'audit:read', 'content:read', 'content:write', 'page:read', 'page:write', 'research:read', 'research:write', 'sites:read', 'sites:write', 'timeline:read', 'timeline:write'];
 export declare const PUBLIC_V1_ROLES: readonly ['viewer', 'member', 'admin', 'owner'];
 export declare const PUBLIC_V1_ERROR_CODES: readonly ['invalid_request', 'unauthorized', 'forbidden', 'not_found', 'site_ambiguous', 'auth_expired', 'entitlement_required', 'quota_exhausted', 'provider_unavailable', 'stale_evidence', 'conflict', 'rate_limited', 'contract_violation', 'internal_error'];
 export declare const PUBLIC_V1_ERROR_STATUS: {

package/dist/v1/core.js

@@ -49,6 +49,7 @@ export const PUBLIC_V1_SCOPES = [
     'sites:read',
     'sites:write',
     'timeline:read',
+    'timeline:write',
 ];
 export const PUBLIC_V1_ROLES = ['viewer', 'member', 'admin', 'owner'];
 export const PUBLIC_V1_ERROR_CODES = [
@@ -154,6 +155,15 @@ function assertExamples(operation) {
             throw new TypeError(`${operation.id}: example response does not satisfy the producer schema`);
     }
 }
+/**
+ * Runs a real `safeParse` per declared example, and runs three times per
+ * operation: `defineOperation`, then `defineRegistry`, then `defineProtocol`
+ * calling `defineRegistry` again. Cheap only because no eager module in the pro
+ * Worker imports a registry: routes take per-feature deep specifiers and the
+ * barrel is test-only. If a registry ever lands in the cold-start closure, move
+ * `docs.examples` to a sibling module the OpenAPI generator and tests import,
+ * because nothing reads them at runtime.
+ */
 function assertOperation(operation) {
     if (!/^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+$/.test(operation.id))
         throw new TypeError(`${operation.id}: operation ID must be a stable dotted lowercase identifier`);