@nuxtseo/protocol 0.1.0

package/dist/v1/audit.js

@@ -0,0 +1,609 @@
+import { z as schema } from 'zod';
+import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
+export const auditSiteParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+});
+export const auditChangesQuerySchema = schema.strictObject({
+    from: schema.coerce.number().int().positive().optional(),
+    to: schema.coerce.number().int().positive().optional(),
+});
+export const auditChangeExampleSchema = defineResponseObject({
+    url: schema.string(),
+    path: schema.string(),
+}, {
+    url: schema.string(),
+    path: schema.string(),
+});
+export const auditChangeCheckSchema = defineResponseObject({
+    key: schema.string(),
+    label: schema.string(),
+    severity: schema.enum(['error', 'warning', 'notice']),
+    subject: schema.enum(['page', 'link-target']),
+    pages: schema.number(),
+}, {
+    key: schema.string(),
+    label: schema.string(),
+    severity: schema.enum(['error', 'warning', 'notice']),
+    subject: schema.enum(['page', 'link-target']),
+    pages: schema.number(),
+});
+export const auditChangeGroupSchema = defineResponseObject({
+    key: schema.string(),
+    label: schema.string(),
+    severity: schema.enum(['error', 'warning', 'notice']),
+    subject: schema.enum(['page', 'link-target']),
+    pages: schema.number(),
+    examples: schema.array(auditChangeExampleSchema.producer),
+    checks: schema.array(auditChangeCheckSchema.producer),
+    spike: schema.boolean(),
+}, {
+    key: schema.string(),
+    label: schema.string(),
+    severity: schema.enum(['error', 'warning', 'notice']),
+    subject: schema.enum(['page', 'link-target']),
+    pages: schema.number(),
+    examples: schema.array(auditChangeExampleSchema.client),
+    checks: schema.array(auditChangeCheckSchema.client),
+    spike: schema.boolean(),
+});
+export const auditChangeFacetSchema = defineResponseObject({
+    groups: schema.array(auditChangeGroupSchema.producer),
+    pages: schema.number(),
+    groupTotal: schema.number(),
+    checkTotal: schema.number(),
+}, {
+    groups: schema.array(auditChangeGroupSchema.client),
+    pages: schema.number(),
+    groupTotal: schema.number(),
+    checkTotal: schema.number(),
+});
+export const auditChangeGenerationSchema = defineResponseObject({
+    generation: schema.number(),
+    buildId: schema.string().nullable(),
+    completedAt: schema.string().nullable(),
+}, {
+    generation: schema.number(),
+    buildId: schema.string().nullable(),
+    completedAt: schema.string().nullable(),
+});
+export const auditRegressionHistoryPointSchema = defineResponseObject({
+    ...auditChangeGenerationSchema.producer.shape,
+    regressedUrls: schema.number(),
+}, {
+    ...auditChangeGenerationSchema.client.shape,
+    regressedUrls: schema.number(),
+});
+export const auditChangesDataSchema = defineResponseObject({
+    state: schema.enum(['changes', 'no-changes', 'no-baseline', 'no-crawl']),
+    verdict: schema.string(),
+    window: schema.strictObject({
+        observedAt: schema.string().nullable(),
+        comparedTo: schema.string().nullable(),
+    }),
+    regressions: auditChangeFacetSchema.producer,
+    resolved: auditChangeFacetSchema.producer,
+    pages: auditChangeFacetSchema.producer,
+    sampled: schema.boolean(),
+    generations: schema.array(auditChangeGenerationSchema.producer),
+    regressionHistory: schema.array(auditRegressionHistoryPointSchema.producer),
+    comparison: schema.strictObject({
+        from: auditChangeGenerationSchema.producer,
+        to: auditChangeGenerationSchema.producer,
+    }).nullable(),
+    clicksAtRisk: schema.number().nullable(),
+}, {
+    state: schema.enum(['changes', 'no-changes', 'no-baseline', 'no-crawl']),
+    verdict: schema.string(),
+    window: schema.looseObject({
+        observedAt: schema.string().nullable(),
+        comparedTo: schema.string().nullable(),
+    }),
+    regressions: auditChangeFacetSchema.client,
+    resolved: auditChangeFacetSchema.client,
+    pages: auditChangeFacetSchema.client,
+    sampled: schema.boolean(),
+    generations: schema.array(auditChangeGenerationSchema.client),
+    regressionHistory: schema.array(auditRegressionHistoryPointSchema.client),
+    comparison: schema.looseObject({
+        from: auditChangeGenerationSchema.client,
+        to: auditChangeGenerationSchema.client,
+    }).nullable(),
+    clicksAtRisk: schema.number().nullable(),
+});
+export const auditChangesResponseSchema = defineSuccessEnvelope(auditChangesDataSchema);
+export const contentDecayRowSchema = defineResponseObject({
+    url: schema.string(),
+    path: schema.string(),
+    clicks: schema.number(),
+    prevClicks: schema.number(),
+    clicksDelta: schema.number(),
+    clicksChangePct: schema.number(),
+    impressions: schema.number(),
+    prevImpressions: schema.number(),
+    position: schema.number().nullable(),
+    prevPosition: schema.number().nullable(),
+}, {
+    url: schema.string(),
+    path: schema.string(),
+    clicks: schema.number(),
+    prevClicks: schema.number(),
+    clicksDelta: schema.number(),
+    clicksChangePct: schema.number(),
+    impressions: schema.number(),
+    prevImpressions: schema.number(),
+    position: schema.number().nullable(),
+    prevPosition: schema.number().nullable(),
+});
+export const auditContentDecayDataSchema = defineResponseObject({
+    connected: schema.boolean(),
+    rows: schema.array(contentDecayRowSchema.producer),
+    total: schema.number(),
+    clicksLost: schema.number(),
+    window: schema.strictObject({
+        startDate: schema.string(),
+        endDate: schema.string(),
+        prevStartDate: schema.string(),
+        prevEndDate: schema.string(),
+    }).nullable(),
+    truncated: schema.boolean(),
+}, {
+    connected: schema.boolean(),
+    rows: schema.array(contentDecayRowSchema.client),
+    total: schema.number(),
+    clicksLost: schema.number(),
+    window: schema.looseObject({
+        startDate: schema.string(),
+        endDate: schema.string(),
+        prevStartDate: schema.string(),
+        prevEndDate: schema.string(),
+    }).nullable(),
+    truncated: schema.boolean(),
+});
+export const auditContentDecayResponseSchema = defineSuccessEnvelope(auditContentDecayDataSchema);
+export const duplicateMemberSchema = defineResponseObject({
+    url: schema.string(),
+    path: schema.string(),
+    clicks: schema.number().nullable(),
+    impressions: schema.number().nullable(),
+}, {
+    url: schema.string(),
+    path: schema.string(),
+    clicks: schema.number().nullable(),
+    impressions: schema.number().nullable(),
+});
+export const duplicateClusterSchema = defineResponseObject({
+    pathPattern: schema.string(),
+    size: schema.number(),
+    exactDuplicates: schema.number(),
+    members: schema.array(duplicateMemberSchema.producer),
+    keepPath: schema.string().nullable(),
+    titles: schema.strictObject({
+        distinct: schema.number(),
+        sampled: schema.number(),
+        verdict: schema.enum(['distinct', 'shared', 'mixed', 'unknown']),
+    }),
+}, {
+    pathPattern: schema.string(),
+    size: schema.number(),
+    exactDuplicates: schema.number(),
+    members: schema.array(duplicateMemberSchema.client),
+    keepPath: schema.string().nullable(),
+    titles: schema.looseObject({
+        distinct: schema.number(),
+        sampled: schema.number(),
+        verdict: schema.enum(['distinct', 'shared', 'mixed', 'unknown']),
+    }),
+});
+export const auditDuplicateClustersDataSchema = defineResponseObject({
+    connected: schema.boolean(),
+    clusters: schema.array(duplicateClusterSchema.producer),
+    total: schema.number(),
+    pagesAffected: schema.number(),
+}, {
+    connected: schema.boolean(),
+    clusters: schema.array(duplicateClusterSchema.client),
+    total: schema.number(),
+    pagesAffected: schema.number(),
+});
+export const auditDuplicateClustersResponseSchema = defineSuccessEnvelope(auditDuplicateClustersDataSchema);
+export const linkOpportunityRowSchema = defineResponseObject({
+    sourceUrl: schema.string(),
+    sourcePath: schema.string(),
+    sourceRank: schema.number().nullable(),
+    targetUrl: schema.string(),
+    targetPath: schema.string(),
+    phrase: schema.string(),
+    snippet: schema.string(),
+    impressions: schema.number(),
+    clicks: schema.number(),
+    position: schema.number(),
+}, {
+    sourceUrl: schema.string(),
+    sourcePath: schema.string(),
+    sourceRank: schema.number().nullable(),
+    targetUrl: schema.string(),
+    targetPath: schema.string(),
+    phrase: schema.string(),
+    snippet: schema.string(),
+    impressions: schema.number(),
+    clicks: schema.number(),
+    position: schema.number(),
+});
+export const auditLinkOpportunitiesDataSchema = defineResponseObject({
+    connected: schema.boolean(),
+    textUnavailable: schema.boolean(),
+    rows: schema.array(linkOpportunityRowSchema.producer),
+    total: schema.number(),
+    pagesScanned: schema.number(),
+    pagesTotal: schema.number(),
+}, {
+    connected: schema.boolean(),
+    textUnavailable: schema.boolean(),
+    rows: schema.array(linkOpportunityRowSchema.client),
+    total: schema.number(),
+    pagesScanned: schema.number(),
+    pagesTotal: schema.number(),
+});
+export const auditLinkOpportunitiesResponseSchema = defineSuccessEnvelope(auditLinkOpportunitiesDataSchema);
+export const templateSlotSchema = defineResponseObject({
+    url: schema.string(),
+    path: schema.string(),
+    templateLinks: schema.number(),
+    sourcePages: schema.number(),
+    locations: schema.array(schema.string()),
+    share: schema.number(),
+    clicks: schema.number().nullable(),
+}, {
+    url: schema.string(),
+    path: schema.string(),
+    templateLinks: schema.number(),
+    sourcePages: schema.number(),
+    locations: schema.array(schema.string()),
+    share: schema.number(),
+    clicks: schema.number().nullable(),
+});
+export const deadEndGroupSchema = defineResponseObject({
+    label: schema.string(),
+    pages: schema.number(),
+    examples: schema.array(schema.string()),
+    topRank: schema.number().nullable(),
+    singleUrl: schema.string().nullable(),
+}, {
+    label: schema.string(),
+    pages: schema.number(),
+    examples: schema.array(schema.string()),
+    topRank: schema.number().nullable(),
+    singleUrl: schema.string().nullable(),
+});
+export const genericAnchorSchema = defineResponseObject({
+    anchor: schema.string(),
+    links: schema.number(),
+    targets: schema.number(),
+    exampleTargets: schema.array(schema.string()),
+}, {
+    anchor: schema.string(),
+    links: schema.number(),
+    targets: schema.number(),
+    exampleTargets: schema.array(schema.string()),
+});
+export const auditLinkStructureDataSchema = defineResponseObject({
+    gscConnected: schema.boolean(),
+    internalLinks: schema.number(),
+    templateLinks: schema.number(),
+    templateTargets: schema.number(),
+    editorialLinks: schema.number(),
+    editorialTargets: schema.number(),
+    templateSlots: schema.array(templateSlotSchema.producer),
+    templateSlotTotal: schema.number(),
+    deadEnds: schema.array(deadEndGroupSchema.producer),
+    deadEndGroupTotal: schema.number(),
+    deadEndPageTotal: schema.number(),
+    deadEndScanTruncated: schema.boolean(),
+    genericAnchors: schema.array(genericAnchorSchema.producer),
+    genericAnchorTotal: schema.number(),
+    genericAnchorLinks: schema.number(),
+}, {
+    gscConnected: schema.boolean(),
+    internalLinks: schema.number(),
+    templateLinks: schema.number(),
+    templateTargets: schema.number(),
+    editorialLinks: schema.number(),
+    editorialTargets: schema.number(),
+    templateSlots: schema.array(templateSlotSchema.client),
+    templateSlotTotal: schema.number(),
+    deadEnds: schema.array(deadEndGroupSchema.client),
+    deadEndGroupTotal: schema.number(),
+    deadEndPageTotal: schema.number(),
+    deadEndScanTruncated: schema.boolean(),
+    genericAnchors: schema.array(genericAnchorSchema.client),
+    genericAnchorTotal: schema.number(),
+    genericAnchorLinks: schema.number(),
+});
+export const auditLinkStructureResponseSchema = defineSuccessEnvelope(auditLinkStructureDataSchema);
+const auditReadSemantics = {
+    kind: 'query',
+    sideEffects: 'none',
+    retry: 'idempotent',
+    readConsistency: 'primary',
+};
+const auditReadAuth = {
+    credentials: ['session', 'api_token'],
+    scopes: ['audit:read'],
+    minimumRole: 'viewer',
+    ownership: 'site',
+};
+const auditReadErrors = [
+    'invalid_request',
+    'unauthorized',
+    'auth_expired',
+    'forbidden',
+    'not_found',
+    'rate_limited',
+    'provider_unavailable',
+    'contract_violation',
+    'internal_error',
+];
+const auditReadResources = {
+    reads: [{ type: 'site.audit', idFrom: 'params.siteId' }],
+    changes: [],
+};
+const auditReadPolicy = {
+    rate: publicV1StandardRatePolicy,
+    idempotency: { _tag: 'none' },
+    entitlement: null,
+    meter: null,
+};
+export const auditChangesOperation = defineOperation({
+    id: 'audit.changes',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/audit/changes',
+    visibility: 'public',
+    semantics: auditReadSemantics,
+    auth: auditReadAuth,
+    request: {
+        params: auditSiteParamsSchema,
+        query: auditChangesQuerySchema,
+        headers: null,
+        body: null,
+    },
+    responses: { 200: auditChangesResponseSchema },
+    errors: auditReadErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: auditReadResources,
+    policy: auditReadPolicy,
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Read audit changes',
+        description: 'Compares published crawl generations and keeps no crawl, no baseline, no changes and observed changes as distinct states.',
+        tags: ['Audit'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: {} },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            state: 'no-baseline',
+                            verdict: '',
+                            window: { observedAt: '2026-08-10T01:30:00.000Z', comparedTo: null },
+                            regressions: { groups: [], pages: 0, groupTotal: 0, checkTotal: 0 },
+                            resolved: { groups: [], pages: 0, groupTotal: 0, checkTotal: 0 },
+                            pages: { groups: [], pages: 0, groupTotal: 0, checkTotal: 0 },
+                            sampled: false,
+                            generations: [{ generation: 4, buildId: 'build_01JXYZ', completedAt: '2026-08-10T01:30:00.000Z' }],
+                            regressionHistory: [],
+                            comparison: null,
+                            clicksAtRisk: null,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const auditContentDecayOperation = defineOperation({
+    id: 'audit.content.decay',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/audit/content-decay',
+    visibility: 'public',
+    semantics: auditReadSemantics,
+    auth: auditReadAuth,
+    request: { params: auditSiteParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: auditContentDecayResponseSchema },
+    errors: auditReadErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: auditReadResources,
+    policy: auditReadPolicy,
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Read content decay',
+        description: 'Lists crawled pages losing Search Console clicks against the prior equal-length window, including coverage state and aggregate loss.',
+        tags: ['Audit'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            connected: true,
+                            rows: [{
+                                    url: 'https://example.com/guide',
+                                    path: '/guide',
+                                    clicks: 12,
+                                    prevClicks: 30,
+                                    clicksDelta: -18,
+                                    clicksChangePct: -60,
+                                    impressions: 400,
+                                    prevImpressions: 620,
+                                    position: 8.4,
+                                    prevPosition: 5.1,
+                                }],
+                            total: 1,
+                            clicksLost: 18,
+                            window: {
+                                startDate: '2026-07-13',
+                                endDate: '2026-08-09',
+                                prevStartDate: '2026-06-15',
+                                prevEndDate: '2026-07-12',
+                            },
+                            truncated: false,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const auditDuplicateClustersOperation = defineOperation({
+    id: 'audit.duplicate.clusters',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/audit/duplicates',
+    visibility: 'public',
+    semantics: auditReadSemantics,
+    auth: auditReadAuth,
+    request: { params: auditSiteParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: auditDuplicateClustersResponseSchema },
+    errors: auditReadErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: auditReadResources,
+    policy: auditReadPolicy,
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Read duplicate clusters',
+        description: 'Returns unresolved near-duplicate route families, member evidence, title distinctness and an optional traffic-backed keep candidate.',
+        tags: ['Audit'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            connected: true,
+                            clusters: [{
+                                    pathPattern: '/guides/*',
+                                    size: 3,
+                                    exactDuplicates: 2,
+                                    members: [{ url: 'https://example.com/guides/alpha', path: '/guides/alpha', clicks: 14, impressions: 200 }],
+                                    keepPath: '/guides/alpha',
+                                    titles: { distinct: 1, sampled: 3, verdict: 'shared' },
+                                }],
+                            total: 1,
+                            pagesAffected: 3,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const auditLinkOpportunitiesOperation = defineOperation({
+    id: 'audit.link.opportunities',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/audit/link-opportunities',
+    visibility: 'public',
+    semantics: auditReadSemantics,
+    auth: auditReadAuth,
+    request: { params: auditSiteParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: auditLinkOpportunitiesResponseSchema },
+    errors: auditReadErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: auditReadResources,
+    policy: auditReadPolicy,
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Read link opportunities',
+        description: 'Returns source pages that mention a target query without linking to its ranking page, with crawl coverage disclosed.',
+        tags: ['Audit'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            connected: true,
+                            textUnavailable: false,
+                            rows: [{
+                                    sourceUrl: 'https://example.com/handbook',
+                                    sourcePath: '/handbook',
+                                    sourceRank: 72,
+                                    targetUrl: 'https://example.com/guide',
+                                    targetPath: '/guide',
+                                    phrase: 'technical SEO guide',
+                                    snippet: 'Read our technical SEO guide before launch.',
+                                    impressions: 900,
+                                    clicks: 18,
+                                    position: 8.2,
+                                }],
+                            total: 1,
+                            pagesScanned: 152,
+                            pagesTotal: 154,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const auditLinkStructureOperation = defineOperation({
+    id: 'audit.link.structure',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/audit/link-structure',
+    visibility: 'public',
+    semantics: auditReadSemantics,
+    auth: auditReadAuth,
+    request: { params: auditSiteParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: auditLinkStructureResponseSchema },
+    errors: auditReadErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: auditReadResources,
+    policy: auditReadPolicy,
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Read link structure',
+        description: 'Summarizes internal link allocation across template slots, dead-end route families and generic editorial anchors.',
+        tags: ['Audit'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            gscConnected: true,
+                            internalLinks: 1400,
+                            templateLinks: 900,
+                            templateTargets: 12,
+                            editorialLinks: 500,
+                            editorialTargets: 120,
+                            templateSlots: [{
+                                    url: 'https://example.com/pricing',
+                                    path: '/pricing',
+                                    templateLinks: 120,
+                                    sourcePages: 118,
+                                    locations: ['nav', 'footer'],
+                                    share: 0.13,
+                                    clicks: 40,
+                                }],
+                            templateSlotTotal: 12,
+                            deadEnds: [{ label: '/archive/*', pages: 5, examples: ['/archive/2024'], topRank: 18, singleUrl: null }],
+                            deadEndGroupTotal: 1,
+                            deadEndPageTotal: 5,
+                            deadEndScanTruncated: false,
+                            genericAnchors: [{ anchor: 'click here', links: 9, targets: 4, exampleTargets: ['/guide'] }],
+                            genericAnchorTotal: 1,
+                            genericAnchorLinks: 9,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const auditV1Registry = defineRegistry({
+    feature: 'audit',
+    operations: {
+        changes: auditChangesOperation,
+        contentDecay: auditContentDecayOperation,
+        duplicateClusters: auditDuplicateClustersOperation,
+        linkOpportunities: auditLinkOpportunitiesOperation,
+        linkStructure: auditLinkStructureOperation,
+    },
+});