@nuxtseo/protocol 0.1.0

package/dist/v1/performance.js

@@ -0,0 +1,198 @@
+import { z as schema } from 'zod';
+import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
+export const performanceSiteParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+});
+const nullableMetricSchema = schema.number().nullable();
+export const performanceScoreSummarySchema = defineResponseObject({
+    median: nullableMetricSchema,
+    worst: nullableMetricSchema,
+    best: nullableMetricSchema,
+}, {
+    median: nullableMetricSchema,
+    worst: nullableMetricSchema,
+    best: nullableMetricSchema,
+});
+export const performanceCategorySummarySchema = defineResponseObject({
+    median: nullableMetricSchema,
+    worst: nullableMetricSchema,
+}, {
+    median: nullableMetricSchema,
+    worst: nullableMetricSchema,
+});
+export const performanceVitalSummarySchema = defineResponseObject({
+    median: nullableMetricSchema,
+    worst: nullableMetricSchema,
+    statusCounts: schema.strictObject({
+        good: schema.number().int().nonnegative(),
+        ni: schema.number().int().nonnegative(),
+        poor: schema.number().int().nonnegative(),
+    }),
+}, {
+    median: nullableMetricSchema,
+    worst: nullableMetricSchema,
+    statusCounts: schema.looseObject({
+        good: schema.number().int().nonnegative(),
+        ni: schema.number().int().nonnegative(),
+        poor: schema.number().int().nonnegative(),
+    }),
+});
+export const sitePerformanceHealthSchema = defineResponseObject({
+    perf: performanceScoreSummarySchema.producer,
+    a11y: performanceCategorySummarySchema.producer,
+    bestPractices: performanceCategorySummarySchema.producer,
+    seo: performanceCategorySummarySchema.producer,
+    lcp: performanceVitalSummarySchema.producer,
+    tbt: performanceVitalSummarySchema.producer,
+    cls: performanceVitalSummarySchema.producer,
+    scannedPageCount: schema.number().int().nonnegative(),
+    lastScanAt: schema.string().datetime().nullable(),
+}, {
+    perf: performanceScoreSummarySchema.client,
+    a11y: performanceCategorySummarySchema.client,
+    bestPractices: performanceCategorySummarySchema.client,
+    seo: performanceCategorySummarySchema.client,
+    lcp: performanceVitalSummarySchema.client,
+    tbt: performanceVitalSummarySchema.client,
+    cls: performanceVitalSummarySchema.client,
+    scannedPageCount: schema.number().int().nonnegative(),
+    lastScanAt: schema.string().datetime().nullable(),
+});
+export const sitePerformanceScanSchema = defineResponseObject({
+    scanId: schema.string().min(1),
+    url: schema.string().url(),
+    completedAt: schema.string().datetime().nullable(),
+    perf: nullableMetricSchema,
+    a11y: nullableMetricSchema,
+    bestPractices: nullableMetricSchema,
+    seo: nullableMetricSchema,
+    lcp: nullableMetricSchema,
+    tbt: nullableMetricSchema,
+    cls: nullableMetricSchema,
+}, {
+    scanId: schema.string().min(1),
+    url: schema.string().url(),
+    completedAt: schema.string().datetime().nullable(),
+    perf: nullableMetricSchema,
+    a11y: nullableMetricSchema,
+    bestPractices: nullableMetricSchema,
+    seo: nullableMetricSchema,
+    lcp: nullableMetricSchema,
+    tbt: nullableMetricSchema,
+    cls: nullableMetricSchema,
+});
+export const sitePerformanceRouteSchema = defineResponseObject({
+    pageId: schema.string().min(1),
+    path: schema.string(),
+    url: schema.string().url(),
+    latestScanId: schema.string().min(1).nullable(),
+    completedAt: schema.string().datetime().nullable(),
+    perf: nullableMetricSchema,
+    a11y: nullableMetricSchema,
+    bestPractices: nullableMetricSchema,
+    seo: nullableMetricSchema,
+    lcp: nullableMetricSchema,
+    tbt: nullableMetricSchema,
+    cls: nullableMetricSchema,
+}, {
+    pageId: schema.string().min(1),
+    path: schema.string(),
+    url: schema.string().url(),
+    latestScanId: schema.string().min(1).nullable(),
+    completedAt: schema.string().datetime().nullable(),
+    perf: nullableMetricSchema,
+    a11y: nullableMetricSchema,
+    bestPractices: nullableMetricSchema,
+    seo: nullableMetricSchema,
+    lcp: nullableMetricSchema,
+    tbt: nullableMetricSchema,
+    cls: nullableMetricSchema,
+});
+export const sitePerformanceOverviewDataSchema = defineResponseObject({
+    health: sitePerformanceHealthSchema.producer.nullable(),
+    homepage: sitePerformanceScanSchema.producer.nullable(),
+    homepageDesktop: sitePerformanceScanSchema.producer.nullable(),
+    routes: schema.array(sitePerformanceRouteSchema.producer),
+    routesDesktop: schema.array(sitePerformanceRouteSchema.producer),
+}, {
+    health: sitePerformanceHealthSchema.client.nullable(),
+    homepage: sitePerformanceScanSchema.client.nullable(),
+    homepageDesktop: sitePerformanceScanSchema.client.nullable(),
+    routes: schema.array(sitePerformanceRouteSchema.client),
+    routesDesktop: schema.array(sitePerformanceRouteSchema.client),
+});
+export const sitePerformanceOverviewResponseSchema = defineSuccessEnvelope(sitePerformanceOverviewDataSchema);
+export const sitePerformanceOverviewOperation = defineOperation({
+    id: 'page.performance',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/performance',
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'primary' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['page:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: { params: performanceSiteParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: sitePerformanceOverviewResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'not_found',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: {
+        reads: [{ type: 'site.page', idFrom: 'params.siteId' }],
+        changes: [],
+    },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Get Site Performance',
+        description: 'Returns stored fleet-level Lighthouse health and the latest mobile and desktop evidence for monitored Pages. Use Page inspection for one Page.',
+        tags: ['Pages'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            health: {
+                                perf: { median: 82, worst: 68, best: 94 },
+                                a11y: { median: 96, worst: 91 },
+                                bestPractices: { median: 92, worst: 86 },
+                                seo: { median: 98, worst: 94 },
+                                lcp: { median: 2200, worst: 4100, statusCounts: { good: 3, ni: 1, poor: 1 } },
+                                tbt: { median: 180, worst: 650, statusCounts: { good: 3, ni: 1, poor: 1 } },
+                                cls: { median: 80, worst: 260, statusCounts: { good: 4, ni: 0, poor: 1 } },
+                                scannedPageCount: 5,
+                                lastScanAt: '2026-08-10T01:00:00.000Z',
+                            },
+                            homepage: null,
+                            homepageDesktop: null,
+                            routes: [],
+                            routesDesktop: [],
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const performanceV1Registry = defineRegistry({
+    feature: 'page',
+    operations: {
+        overview: sitePerformanceOverviewOperation,
+    },
+});