@nuxtseo/protocol 0.5.7 → 0.5.9

package/dist/v1/performance.js

@@ -355,26 +355,76 @@ export const fieldVitalFindingsQuerySchema = schema.strictObject({
     limit: schema.coerce.number().int().min(1).max(50).default(20),
     offset: schema.coerce.number().int().min(0).default(0),
 });
-export const fieldVitalFindingSchema = defineResponseObject({
-    metric: schema.enum(['lcp', 'inp', 'cls']),
+const fieldVitalFindingBaseShape = {
     severity: fieldVitalRatingSchema,
     p75: schema.number().nullable(),
     route: schema.string(),
     selector: schema.string(),
     estimatedViews: schema.number(),
+    /** Share of sampled views rated poor, 0 to 1. Null when the provider sent no distribution. */
+    poorFraction: schema.number().min(0).max(1).nullable(),
+    /** The blocking script a lab Scan of the same route found. Null when no Scan matches. */
+    labHint: schema.string().nullable(),
     fixPrompt: schema.string().min(1),
-}, {
-    metric: schema.enum(['lcp', 'inp', 'cls']),
-    severity: fieldVitalRatingSchema,
-    p75: schema.number().nullable(),
-    route: schema.string(),
-    selector: schema.string(),
-    estimatedViews: schema.number(),
-    fixPrompt: schema.string().min(1),
-});
+};
+// A newer client reading an older server sees no structured fields, so the
+// client marks each one optional.
+const fieldVitalFindingBaseClientShape = {
+    ...fieldVitalFindingBaseShape,
+    poorFraction: fieldVitalFindingBaseShape.poorFraction.optional(),
+    labHint: fieldVitalFindingBaseShape.labHint.optional(),
+};
+/** Mean LCP sub-phase durations in milliseconds across the sampled views. */
+const fieldVitalLcpPhasesShape = {
+    timeToFirstByte: schema.number().nullable(),
+    resourceLoadDelay: schema.number().nullable(),
+    resourceLoadTime: schema.number().nullable(),
+    elementRenderDelay: schema.number().nullable(),
+};
+const fieldVitalLcpShape = {
+    /** Host and path of the LCP resource. Null for a text LCP element. */
+    resource: schema.string().nullable(),
+    /** The `fetchpriority` the browser saw on the LCP resource. */
+    fetchPriority: schema.string().nullable(),
+    /** How the resource was requested, for example `img` or `css`. */
+    initiatorType: schema.string().nullable(),
+    phases: schema.strictObject(fieldVitalLcpPhasesShape),
+};
+/**
+ * One failing real-user vital attributed to a DOM element. The fields after
+ * `selector` depend on `metric`: an LCP finding names its resource and phases,
+ * an INP finding names the interaction. `fixPrompt` restates the same facts as
+ * prose for an agent to apply.
+ */
+export const fieldVitalFindingSchema = {
+    producer: schema.discriminatedUnion('metric', [
+        schema.strictObject({ metric: schema.literal('lcp'), ...fieldVitalFindingBaseShape, ...fieldVitalLcpShape }),
+        schema.strictObject({ metric: schema.literal('inp'), ...fieldVitalFindingBaseShape, interaction: schema.string().nullable() }),
+        schema.strictObject({ metric: schema.literal('cls'), ...fieldVitalFindingBaseShape }),
+    ]),
+    client: schema.discriminatedUnion('metric', [
+        schema.looseObject({
+            metric: schema.literal('lcp'),
+            ...fieldVitalFindingBaseClientShape,
+            resource: fieldVitalLcpShape.resource.optional(),
+            fetchPriority: fieldVitalLcpShape.fetchPriority.optional(),
+            initiatorType: fieldVitalLcpShape.initiatorType.optional(),
+            phases: schema.looseObject(fieldVitalLcpPhasesShape).optional(),
+        }),
+        schema.looseObject({ metric: schema.literal('inp'), ...fieldVitalFindingBaseClientShape, interaction: schema.string().nullable().optional() }),
+        schema.looseObject({ metric: schema.literal('cls'), ...fieldVitalFindingBaseClientShape }),
+    ]),
+};
+/** The dates the Web Analytics provider aggregated, inclusive, as `YYYY-MM-DD`. */
+const fieldVitalWindowShape = {
+    from: schema.iso.date(),
+    to: schema.iso.date(),
+};
 export const fieldVitalFindingsDataSchema = defineResponseObject({
     source: schema.string().nullable(),
     message: schema.string().nullable(),
+    /** Null when no Web Analytics provider answered. */
+    window: schema.strictObject(fieldVitalWindowShape).nullable(),
     findings: schema.array(fieldVitalFindingSchema.producer),
     total: schema.number().int().nonnegative(),
     limit: schema.number().int().positive(),
@@ -382,6 +432,7 @@ export const fieldVitalFindingsDataSchema = defineResponseObject({
 }, {
     source: schema.string().nullable(),
     message: schema.string().nullable(),
+    window: schema.looseObject(fieldVitalWindowShape).nullable().optional(),
     findings: schema.array(fieldVitalFindingSchema.client),
     total: schema.number().int().nonnegative(),
     limit: schema.number().int().positive(),
@@ -427,7 +478,7 @@ export const fieldVitalFindingsOperation = defineOperation({
     lifecycle: { introduced: '1.2.0' },
     docs: {
         summary: 'List field Core Web Vitals findings',
-        description: 'Returns each failing real-user vital attributed to the DOM element behind it, with the p75, the CSS selector, and a ready-to-apply fix prompt. It requires a connected Web Analytics provider. If no provider is connected, findings is empty and message says so.',
+        description: 'Returns each failing real-user vital attributed to the DOM element behind it, with the p75, the CSS selector, and a ready-to-apply fix prompt. An LCP finding also names its resource, fetchPriority and phases. An INP finding names the interaction. window gives the dates the provider aggregated. It requires a connected Web Analytics provider. If no provider is connected, findings is empty and message says so.',
         tags: ['Pages'],
         examples: [{
                 request: { params: { siteId: 'site_01JXYZ' }, query: { onlyFailing: '1', limit: 20, offset: 0 } },
@@ -437,6 +488,7 @@ export const fieldVitalFindingsOperation = defineOperation({
                         data: {
                             source: 'cloudflare',
                             message: null,
+                            window: { from: '2026-07-13', to: '2026-08-09' },
                             findings: [{
                                     metric: 'lcp',
                                     severity: 'poor',
@@ -444,6 +496,12 @@ export const fieldVitalFindingsOperation = defineOperation({
                                     route: '/blog',
                                     selector: 'main > img.hero',
                                     estimatedViews: 1840,
+                                    poorFraction: 0.31,
+                                    labHint: null,
+                                    resource: 'example.com/images/hero.jpg',
+                                    fetchPriority: 'auto',
+                                    initiatorType: 'img',
+                                    phases: { timeToFirstByte: 600, resourceLoadDelay: 1900, resourceLoadTime: 1200, elementRenderDelay: 600 },
                                     fixPrompt: 'The LCP element on /blog is main > img.hero at 4300ms.',
                                 }],
                             total: 1,
@@ -475,31 +533,130 @@ const scanScoresShape = {
     bestPractices: nullableMetricSchema,
     seo: nullableMetricSchema,
 };
-export const performanceScanSummarySchema = defineResponseObject({
+/**
+ * Why a Scan started. `claim-recheck` follows a claimed Action. `deploy`
+ * follows a new Nuxt build. `confirmation` repeats a Scan that looked like a
+ * regression.
+ */
+export const PERFORMANCE_SCAN_TRIGGERS = ['scheduled', 'manual', 'claim-recheck', 'deploy', 'confirmation'];
+/**
+ * Why a Scan failed. `timeout`, `unavailable`, `quota`, `rejected`, `network`,
+ * `empty`, `malformed` and `oversize` describe the PageSpeed Insights request.
+ * The rest describe the pipeline around it. `rejected` means PSI refused the
+ * URL, so a retry of the same URL fails the same way.
+ */
+export const PERFORMANCE_SCAN_FAILURE_KINDS = [
+    'timeout',
+    'unavailable',
+    'quota',
+    'rejected',
+    'network',
+    'empty',
+    'malformed',
+    'oversize',
+    'artifact-missing',
+    'processing',
+    'abandoned',
+    'unqueued',
+    'monitoring-changed',
+    'internal',
+];
+/**
+ * Fields every Scan carries, in the Scan list and the Scan read alike.
+ * `failureKind` and `error` are null unless `status` is `failed`. A Scan that
+ * failed before failure kinds were recorded has a null `failureKind`.
+ */
+const scanBaseShape = {
     id: schema.string().min(1),
     url: schema.string().min(1),
-    strategy: schema.string().min(1),
-    status: schema.string().min(1),
-    trigger: schema.string().nullable(),
+    strategy: schema.enum(['mobile', 'desktop']),
+    status: schema.enum(['running', 'complete', 'failed']),
+    trigger: schema.enum(PERFORMANCE_SCAN_TRIGGERS),
+    failureKind: schema.enum(PERFORMANCE_SCAN_FAILURE_KINDS).nullable(),
+    error: schema.string().nullable(),
+    lighthouseVersion: schema.string().nullable(),
     scores: schema.strictObject(scanScoresShape),
     lcp: nullableMetricSchema,
     tbt: nullableMetricSchema,
     cls: nullableMetricSchema,
     completedAt: schema.string().datetime().nullable(),
-    error: schema.string().nullable(),
-}, {
+};
+// Strings, not enums, so an older client accepts a status, trigger or failure
+// kind that a newer server adds. Fields added after 1.2.0 are optional.
+const scanBaseClientShape = {
     id: schema.string().min(1),
     url: schema.string().min(1),
     strategy: schema.string().min(1),
     status: schema.string().min(1),
-    trigger: schema.string().nullable(),
+    trigger: schema.string().nullable().optional(),
+    failureKind: schema.string().nullable().optional(),
+    error: schema.string().nullable().optional(),
+    lighthouseVersion: schema.string().nullable().optional(),
     scores: schema.looseObject(scanScoresShape),
     lcp: nullableMetricSchema,
     tbt: nullableMetricSchema,
     cls: nullableMetricSchema,
     completedAt: schema.string().datetime().nullable(),
-    error: schema.string().nullable(),
-});
+};
+export const performanceScanSummarySchema = defineResponseObject(scanBaseShape, scanBaseClientShape);
+/** Metrics a Scan comparison can name. Same names and units as the Scan fields. */
+export const PERFORMANCE_SCAN_COMPARISON_METRICS = ['perf', 'a11y', 'bestPractices', 'seo', 'lcp', 'tbt', 'cls', 'inp', 'fcp', 'speedIndex', 'ttfb'];
+/** Why two Scans of one Page cannot be compared. */
+export const PERFORMANCE_SCAN_INCOMPATIBILITY_REASONS = [
+    'source',
+    'target-url',
+    'strategy',
+    'lighthouse-version',
+    'form-factor',
+    'cpu-throttling',
+    'network-throttling',
+    'host-browser',
+    'runtime-environment',
+];
+const scanChangeSeveritySchema = schema.enum(['improvement', 'regression', 'neutral']);
+const scanMetricChangeShape = {
+    metric: schema.enum(PERFORMANCE_SCAN_COMPARISON_METRICS),
+    previous: schema.number(),
+    current: schema.number(),
+    delta: schema.number(),
+    severity: scanChangeSeveritySchema,
+};
+/**
+ * This Scan against the previous comparable Scan of the same Page and strategy.
+ * `compared` lists each metric both Scans measured. `incompatible` names why
+ * the two Scans differ, for example a Lighthouse version change. `none` means
+ * no previous Scan was compared, which is always true for the homepage slot.
+ */
+export const performanceScanComparisonSchema = {
+    producer: schema.discriminatedUnion('_tag', [
+        schema.strictObject({
+            _tag: schema.literal('compared'),
+            previousScanId: schema.string().min(1).nullable(),
+            severity: scanChangeSeveritySchema,
+            changes: schema.array(schema.strictObject(scanMetricChangeShape)),
+        }),
+        schema.strictObject({
+            _tag: schema.literal('incompatible'),
+            previousScanId: schema.string().min(1).nullable(),
+            reasons: schema.array(schema.enum(PERFORMANCE_SCAN_INCOMPATIBILITY_REASONS)),
+        }),
+        schema.strictObject({ _tag: schema.literal('none') }),
+    ]),
+    client: schema.discriminatedUnion('_tag', [
+        schema.looseObject({
+            _tag: schema.literal('compared'),
+            previousScanId: schema.string().min(1).nullable(),
+            severity: schema.string().min(1),
+            changes: schema.array(schema.looseObject({ ...scanMetricChangeShape, metric: schema.string().min(1), severity: schema.string().min(1) })),
+        }),
+        schema.looseObject({
+            _tag: schema.literal('incompatible'),
+            previousScanId: schema.string().min(1).nullable(),
+            reasons: schema.array(schema.string().min(1)),
+        }),
+        schema.looseObject({ _tag: schema.literal('none') }),
+    ]),
+};
 export const performanceScansDataSchema = defineResponseObject({
     scans: schema.array(performanceScanSummarySchema.producer),
     total: schema.number().int().nonnegative(),
@@ -546,7 +703,7 @@ export const performanceScansOperation = defineOperation({
     lifecycle: { introduced: '1.2.0' },
     docs: {
         summary: 'List Lighthouse Scans',
-        description: 'Returns retained Lighthouse Scans for the Site, newest first, with the scores and lab vitals each one recorded. A failed Scan carries its error. Use one Scan id with the Scan read for the failing checks behind a score.',
+        description: 'Returns retained Lighthouse Scans for the Site, newest first, with the scores and lab vitals each one recorded. A failed Scan carries its failureKind and error, and its scores are null. Use one Scan id with the Scan read for the failing checks behind a score.',
         tags: ['Pages'],
         examples: [{
                 request: { params: { siteId: 'site_01JXYZ' }, query: { limit: 25 } },
@@ -560,14 +717,30 @@ export const performanceScansOperation = defineOperation({
                                     strategy: 'mobile',
                                     status: 'complete',
                                     trigger: 'scheduled',
+                                    failureKind: null,
+                                    error: null,
+                                    lighthouseVersion: '13.5.0',
                                     scores: { perf: 82, a11y: 96, bestPractices: 92, seo: 98 },
                                     lcp: 2200,
                                     tbt: 180,
                                     cls: 0.08,
                                     completedAt: '2026-08-10T01:00:00.000Z',
-                                    error: null,
+                                }, {
+                                    id: 'scan_01JXZA',
+                                    url: 'https://example.com/blog',
+                                    strategy: 'mobile',
+                                    status: 'failed',
+                                    trigger: 'scheduled',
+                                    failureKind: 'timeout',
+                                    error: 'PSI timed out loading the page',
+                                    lighthouseVersion: null,
+                                    scores: { perf: null, a11y: null, bestPractices: null, seo: null },
+                                    lcp: null,
+                                    tbt: null,
+                                    cls: null,
+                                    completedAt: '2026-08-10T01:05:00.000Z',
                                 }],
-                            total: 1,
+                            total: 2,
                             limit: 25,
                         },
                         meta: { requestId: 'req_01JXYZ', version: '1.0' },
@@ -765,18 +938,11 @@ export const lcpObservedTraceSchema = schema.discriminatedUnion('_tag', [
     }
 });
 export const performanceScanDetailDataSchema = defineResponseObject({
-    id: schema.string().min(1),
-    url: schema.string().min(1),
-    strategy: schema.string().min(1),
-    status: schema.string().min(1),
-    scores: schema.strictObject(scanScoresShape),
-    lcp: nullableMetricSchema,
-    tbt: nullableMetricSchema,
-    cls: nullableMetricSchema,
+    ...scanBaseShape,
     fcp: nullableMetricSchema,
     speedIndex: nullableMetricSchema,
     ttfb: nullableMetricSchema,
-    completedAt: schema.string().datetime().nullable(),
+    comparison: performanceScanComparisonSchema.producer,
     javascript: schema.strictObject(scanJavascriptShape).nullable(),
     observedTrace: lcpObservedTraceSchema.optional(),
     performanceIssues: schema.array(scanPerformanceIssueSchema.producer),
@@ -791,18 +957,11 @@ export const performanceScanDetailDataSchema = defineResponseObject({
     bestPractices: schema.array(scanFailingCheckSchema.producer),
     coverage: schema.strictObject(scanCoverageShape),
 }, {
-    id: schema.string().min(1),
-    url: schema.string().min(1),
-    strategy: schema.string().min(1),
-    status: schema.string().min(1),
-    scores: schema.looseObject(scanScoresShape),
-    lcp: nullableMetricSchema,
-    tbt: nullableMetricSchema,
-    cls: nullableMetricSchema,
+    ...scanBaseClientShape,
     fcp: nullableMetricSchema,
     speedIndex: nullableMetricSchema,
     ttfb: nullableMetricSchema,
-    completedAt: schema.string().datetime().nullable(),
+    comparison: performanceScanComparisonSchema.client.optional(),
     javascript: schema.looseObject(scanJavascriptShape).nullable().optional(),
     observedTrace: lcpObservedTraceSchema.optional(),
     performanceIssues: schema.array(scanPerformanceIssueSchema.client),
@@ -854,7 +1013,7 @@ export const performanceScanDetailOperation = defineOperation({
     lifecycle: { introduced: '1.2.0' },
     docs: {
         summary: 'Get one Lighthouse Scan',
-        description: 'Returns one Scan with the evidence behind its scores: the wasteful assets, the repeat-visit cache policy, the third-party scripts, the LCP element, and every failing accessibility and best-practices check with the CSS selectors and DOM snippets that failed. Read coverage before quoting a total: elements and checks are both capped per Scan.',
+        description: 'Returns one Scan with the evidence behind its scores: the wasteful assets, the repeat-visit cache policy, the third-party scripts, the LCP element, and every failing accessibility and best-practices check with the CSS selectors and DOM snippets that failed. It also returns why the Scan started, the Lighthouse version, and the comparison with the previous Scan of the same Page. A failed Scan carries its failureKind and error. Read coverage before quoting a total: elements and checks are both capped per Scan. A null blockingTime or wastedMs is unmeasured, never zero.',
         tags: ['Pages'],
         examples: [{
                 request: { params: { siteId: 'site_01JXYZ', scanId: 'scan_01JXYZ' } },
@@ -863,9 +1022,13 @@ export const performanceScanDetailOperation = defineOperation({
                     body: {
                         data: {
                             id: 'scan_01JXYZ',
-                            url: 'https://example.com/',
+                            url: 'https://example.com/pricing',
                             strategy: 'mobile',
                             status: 'complete',
+                            trigger: 'scheduled',
+                            failureKind: null,
+                            error: null,
+                            lighthouseVersion: '13.5.0',
                             scores: { perf: 82, a11y: 96, bestPractices: 92, seo: 98 },
                             lcp: 2200,
                             tbt: 180,
@@ -874,6 +1037,15 @@ export const performanceScanDetailOperation = defineOperation({
                             speedIndex: 2400,
                             ttfb: 210,
                             completedAt: '2026-08-10T01:00:00.000Z',
+                            comparison: {
+                                _tag: 'compared',
+                                previousScanId: 'scan_01JXXX',
+                                severity: 'regression',
+                                changes: [
+                                    { metric: 'lcp', previous: 1500, current: 2200, delta: 700, severity: 'regression' },
+                                    { metric: 'perf', previous: 85, current: 82, delta: -3, severity: 'neutral' },
+                                ],
+                            },
                             javascript: null,
                             performanceIssues: [],
                             cachePolicy: [],