@nuxtseo/protocol 0.5.10 → 0.5.11

package/dist/v1/analytics.js

@@ -288,9 +288,224 @@ export const analyticsQueryOperation = defineOperation({
             }],
     },
 });
+export const botActivityParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+});
+export const botActivityQuerySchema = schema.strictObject({
+    days: schema.coerce.number().int().min(1).max(90).default(28),
+    crawler: schema.enum(['googlebot', 'bingbot']).default('googlebot'),
+});
+const googlebotStatusCountsSchema = defineResponseObject({
+    '2xx': schema.number(),
+    '304': schema.number(),
+    'other3xx': schema.number(),
+    '404': schema.number(),
+    '410': schema.number(),
+    'other4xx': schema.number(),
+    '429': schema.number(),
+    '5xx': schema.number(),
+});
+const googlebotContentCountsSchema = defineResponseObject({
+    html: schema.number(),
+    js: schema.number(),
+    css: schema.number(),
+    image: schema.number(),
+    other: schema.number(),
+});
+const googlebotOriginSchema = defineResponseObject({
+    requests: schema.number(),
+    avgMs: schema.number().nullable(),
+    p50Ms: schema.number().nullable(),
+});
+const googlebotDaySchema = defineResponseObject({
+    day: schema.string(),
+    complete: schema.boolean(),
+    requests: schema.number(),
+    bytes: schema.number(),
+    statuses: googlebotStatusCountsSchema.producer,
+    contents: googlebotContentCountsSchema.producer,
+    cacheHits: schema.number(),
+    origin: googlebotOriginSchema.producer,
+}, {
+    day: schema.string(),
+    complete: schema.boolean(),
+    requests: schema.number(),
+    bytes: schema.number(),
+    statuses: googlebotStatusCountsSchema.client,
+    contents: googlebotContentCountsSchema.client,
+    cacheHits: schema.number(),
+    origin: googlebotOriginSchema.client,
+});
+const googlebotErrorPathSchema = defineResponseObject({
+    path: schema.string(),
+    status: schema.number(),
+    requests: schema.number(),
+    lastDay: schema.string(),
+});
+const googlebotCollectionSchema = defineResponseObject({
+    fromDay: schema.string(),
+    toDay: schema.string(),
+    completeThroughDay: schema.string().nullable(),
+});
+const googlebotTotalsSchema = defineResponseObject({
+    requests: schema.number(),
+    statuses: googlebotStatusCountsSchema.producer,
+    contents: googlebotContentCountsSchema.producer,
+    cacheHitShare: schema.number().nullable(),
+    wastedShare: schema.number().nullable(),
+    originAvgMs: schema.number().nullable(),
+}, {
+    requests: schema.number(),
+    statuses: googlebotStatusCountsSchema.client,
+    contents: googlebotContentCountsSchema.client,
+    cacheHitShare: schema.number().nullable(),
+    wastedShare: schema.number().nullable(),
+    originAvgMs: schema.number().nullable(),
+});
+/**
+ * Whether the stored days are still current. `zone_access_missing` names the
+ * exact Cloudflare grant: an account analytics token cannot read zone
+ * analytics, and an OAuth user can withhold that scope.
+ */
+const googlebotAccessSchema = {
+    producer: schema.discriminatedUnion('_tag', [
+        schema.strictObject({ _tag: schema.literal('collecting') }),
+        schema.strictObject({
+            _tag: schema.literal('zone_access_missing'),
+            permissions: schema.array(schema.string()),
+            oauthScopes: schema.array(schema.string()),
+            message: schema.string(),
+        }),
+        schema.strictObject({ _tag: schema.literal('collection_failed'), reason: schema.string(), message: schema.string() }),
+    ]),
+    client: schema.discriminatedUnion('_tag', [
+        schema.looseObject({ _tag: schema.literal('collecting') }),
+        schema.looseObject({
+            _tag: schema.literal('zone_access_missing'),
+            permissions: schema.array(schema.string()),
+            oauthScopes: schema.array(schema.string()),
+            message: schema.string(),
+        }),
+        schema.looseObject({ _tag: schema.literal('collection_failed'), reason: schema.string(), message: schema.string() }),
+    ]),
+};
+export const botActivityDataSchema = defineResponseObject({
+    crawler: schema.enum(['googlebot', 'bingbot']),
+    access: googlebotAccessSchema.producer,
+    collection: googlebotCollectionSchema.producer.nullable(),
+    totals: googlebotTotalsSchema.producer,
+    days: schema.array(googlebotDaySchema.producer),
+    errorPaths: schema.array(googlebotErrorPathSchema.producer),
+}, {
+    crawler: schema.enum(['googlebot', 'bingbot']),
+    access: googlebotAccessSchema.client,
+    collection: googlebotCollectionSchema.client.nullable(),
+    totals: googlebotTotalsSchema.client,
+    days: schema.array(googlebotDaySchema.client),
+    errorPaths: schema.array(googlebotErrorPathSchema.client),
+});
+export const botActivityResponseSchema = defineSuccessEnvelope(botActivityDataSchema);
+export const botActivityOperation = defineOperation({
+    id: 'analytics.bots.activity',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/bot-activity',
+    visibility: 'public',
+    semantics: {
+        kind: 'query',
+        sideEffects: 'none',
+        retry: 'idempotent',
+        readConsistency: 'replica-ok',
+    },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['analytics:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: {
+        params: botActivityParamsSchema,
+        query: botActivityQuerySchema,
+        headers: null,
+        body: null,
+    },
+    responses: { 200: botActivityResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'not_found',
+        'entitlement_required',
+        'conflict',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: {
+        reads: [{ type: 'site.analytics', idFrom: 'params.siteId' }],
+        changes: [],
+    },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: 'growth',
+        meter: null,
+    },
+    lifecycle: { introduced: '1.3.0' },
+    docs: {
+        summary: 'Read Bot Traffic',
+        description: [
+            'Reads verified Googlebot or Bingbot requests to an owned Site, counted per UTC day at its Cloudflare zone.',
+            'Cloudflare verifies the crawler. Search Console serves Crawl Stats only in its UI, so these are edge counts without a discovery or refresh split.',
+            '`days` lists only days a collection covered. A missing day was never collected.',
+            '`access` says whether collection still runs. `zone_access_missing` lists the Cloudflare permissions and OAuth scopes to grant; until then the stored days stop at the last collection.',
+            '`wastedShare` is the share of requests answered with anything except 2xx or 304.',
+            '`errorPaths` lists the most requested 4xx, 429 and 5xx paths. It leaves out 410.',
+        ].join(' '),
+        tags: ['Web Analytics'],
+        examples: [{
+                request: {
+                    params: { siteId: 'site_01JXYZ' },
+                    query: { days: 7 },
+                },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            crawler: 'googlebot',
+                            access: { _tag: 'collecting' },
+                            collection: { fromDay: '2026-09-16', toDay: '2026-10-13', completeThroughDay: '2026-10-12' },
+                            totals: {
+                                requests: 2219,
+                                statuses: { '2xx': 1933, '304': 0, 'other3xx': 60, '404': 51, '410': 1, 'other4xx': 172, '429': 0, '5xx': 2 },
+                                contents: { html: 1702, js: 0, css: 0, image: 341, other: 176 },
+                                cacheHitShare: 0.41,
+                                wastedShare: 0.1289,
+                                originAvgMs: 284,
+                            },
+                            days: [{
+                                    day: '2026-10-12',
+                                    complete: true,
+                                    requests: 322,
+                                    bytes: 9_840_211,
+                                    statuses: { '2xx': 282, '304': 0, 'other3xx': 6, '404': 6, '410': 0, 'other4xx': 27, '429': 0, '5xx': 1 },
+                                    contents: { html: 250, js: 0, css: 0, image: 47, other: 25 },
+                                    cacheHits: 131,
+                                    origin: { requests: 191, avgMs: 302, p50Ms: 188 },
+                                }],
+                            errorPaths: [{ path: '/skills/acme/retired-skill', status: 404, requests: 6, lastDay: '2026-10-12' }],
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
 export const analyticsV1Registry = defineRegistry({
     feature: 'analytics',
     operations: {
         query: analyticsQueryOperation,
+        botActivity: botActivityOperation,
     },
 });

package/dist/v1/sites.js

@@ -224,6 +224,7 @@ const siteStatusCountsShape = {
  */
 const siteStatusDataQualityShape = {
     status: schema.enum(['complete', 'degraded', 'unavailable']),
+    /** Recorded unavailable stage. Null when the assessment has no recorded cause. */
     reason: schema.string().nullable(),
     unavailableProofs: schema.array(schema.string()),
 };