@nuxtseo/protocol 0.2.0 → 0.3.0

package/dist/v1/gsc.js

@@ -1,6 +1,6 @@
 import { canonicalDifferenceKindSchema, gscdumpAnalysisPresetSchema, gscdumpIndexingTransitionFieldSchema, gscdumpTotalsSchema, indexingIssueSchema, } from '@gscdump/contracts';
 import { z as schema } from 'zod';
-import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
+import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1ErrorEnvelope, publicV1PageSchema, publicV1StandardRatePolicy, } from './core.js';
 export const searchConsoleSiteParamsSchema = schema.strictObject({
     siteId: schema.string().min(1),
 });
@@ -76,7 +76,16 @@ export const searchAnalyticsQuerySchema = schema.strictObject({
 });
 const totalsSchema = defineResponseObject(gscdumpTotalsSchema.shape, gscdumpTotalsSchema.shape);
 const representedTotalsSchema = defineResponseObject({ clicks: schema.number(), impressions: schema.number() }, { clicks: schema.number(), impressions: schema.number() });
-const pageRowSchema = defineResponseObject({
+const pageRowShape = {
+    /**
+     * The canonical page URL: origin plus path, with the host twin, the scheme,
+     * the query string and the fragment folded away.
+     *
+     * Search Console reports one row per exact page string, so `https://x/a`,
+     * `https://www.x/a` and `https://x/a?utm=1` arrive as three rows that all
+     * canonicalise to one `url`. `url` therefore repeats across rows. Group by
+     * `gscPage` to reproduce `total`.
+     */
     url: schema.string().min(1),
     clicks: schema.number(),
     impressions: schema.number(),
@@ -84,9 +93,21 @@ const pageRowSchema = defineResponseObject({
     pos: schema.number(),
     keyword: schema.string().nullable(),
     prevClicks: schema.number().optional(),
+    prevImpressions: schema.number().optional(),
     prevPos: schema.number().optional(),
     change: schema.number().nullable(),
-});
+};
+/**
+ * The exact page string Search Console reported, before canonicalisation.
+ * This is the dimension `total` counts, so it is unique within `rows`.
+ *
+ * A producer must send it. A client treats it as optional, because a client
+ * newer than the deployed server reads answers that predate the field.
+ * `.nullable()` alone still demands the key, which fails every response the
+ * deployed server sends today.
+ */
+const gscPageField = schema.string().nullable();
+const pageRowSchema = defineResponseObject({ ...pageRowShape, gscPage: gscPageField }, { ...pageRowShape, gscPage: gscPageField.optional() });
 const keywordRowSchema = defineResponseObject({
     keyword: schema.string().min(1),
     clicks: schema.number(),
@@ -95,6 +116,7 @@ const keywordRowSchema = defineResponseObject({
     pos: schema.number(),
     topPage: schema.string().nullable(),
     prevClicks: schema.number().optional(),
+    prevImpressions: schema.number().optional(),
     prevPos: schema.number().optional(),
     change: schema.number().nullable(),
 });
@@ -126,6 +148,11 @@ function breakdownSchema(view, row) {
         representedTotals: representedTotalsSchema.producer,
         representedTotalsScope: schema.string().min(1),
         rows: schema.array(row.producer),
+        /**
+         * The converged list envelope. `page.total` repeats the flat `total`,
+         * which counts the whole upstream population rather than this page.
+         */
+        page: publicV1PageSchema.producer,
     }, {
         site: schema.string().min(1),
         view: schema.literal(view),
@@ -136,6 +163,7 @@ function breakdownSchema(view, row) {
         representedTotals: representedTotalsSchema.client,
         representedTotalsScope: schema.string().min(1),
         rows: schema.array(row.client),
+        page: publicV1PageSchema.client.optional(),
     });
 }
 const pagesDataSchema = breakdownSchema('pages', pageRowSchema);
@@ -221,9 +249,12 @@ const analysisRowSchema = defineResponseObject({
     clicks: schema.number(),
     impressions: schema.number(),
     ctr: schema.number(),
-    pos: schema.number(),
+    // Null when the keyword has no row in the current window (a `decay` keyword
+    // that vanished). Zero would read as a ranking position.
+    pos: schema.number().nullable(),
     page: schema.string().optional(),
     prevClicks: schema.number().optional(),
+    prevImpressions: schema.number().optional(),
     prevPos: schema.number().optional(),
     potentialClicks: schema.number().optional(),
     opportunityScore: schema.number().optional(),
@@ -510,7 +541,7 @@ export const searchAnalyticsQueryOperation = defineOperation({
         tags: ['Sites', 'Search'],
         examples: [{
                 request: { params: { siteId: 'site_01JXYZ' }, query: { view: 'keywords' } },
-                response: { status: 200, body: { data: { site: 'https://example.com', view: 'keywords', period: '28d', total: 1, totals: { clicks: 12, impressions: 100, ctr: 0.12, position: 4 }, totalsScope: 'full upstream query population', representedTotals: { clicks: 12, impressions: 100 }, representedTotalsScope: 'returned rows', rows: [{ keyword: 'nuxt seo', clicks: 12, impressions: 100, ctr: 0.12, pos: 4, topPage: 'https://example.com/docs', change: 2 }] }, meta: { requestId: 'req_01JXYZ', version: '1.0' } } },
+                response: { status: 200, body: { data: { site: 'https://example.com', view: 'keywords', period: '28d', total: 1, totals: { clicks: 12, impressions: 100, ctr: 0.12, position: 4 }, totalsScope: 'full upstream query population', representedTotals: { clicks: 12, impressions: 100 }, representedTotalsScope: 'returned rows', rows: [{ keyword: 'nuxt seo', clicks: 12, impressions: 100, ctr: 0.12, pos: 4, topPage: 'https://example.com/docs', change: 2 }], page: { total: 1, limit: 25, offset: 0, hasMore: false } }, meta: { requestId: 'req_01JXYZ', version: '1.0' } } },
             }],
     },
 });

package/dist/v1/pages.d.ts

@@ -61,6 +61,11 @@ export declare const pageObservationSchema: import("./core.js").CompatibleRespon
         unmonitored: "unmonitored";
     }>>;
 }, z.core.$strip>>;
+/**
+ * The latest Lighthouse Scan for one page. The four category scores run from 0
+ * to 100. `lcp` and `tbt` are milliseconds. `cls` is the unitless Cumulative
+ * Layout Shift value at the Lighthouse scale, so `0.1` is the "good" threshold.
+ */
 export declare const pageLighthouseSchema: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
     readonly scanId: z.ZodString;
     readonly strategy: z.ZodEnum<{
@@ -142,6 +147,12 @@ export declare const pageInspectDataSchema: import("./core.js").CompatibleRespon
                 unmonitored: "unmonitored";
             }>>;
         }, z.core.$strip>>;
+        page: z.ZodObject<{
+            readonly total: z.ZodNumber;
+            readonly limit: z.ZodNumber;
+            readonly offset: z.ZodNumber;
+            readonly hasMore: z.ZodBoolean;
+        }, z.core.$strip>;
         total: z.ZodNumber;
         coverage: z.ZodEnum<{
             "issues-open": "issues-open";
@@ -208,6 +219,12 @@ export declare const pageInspectDataSchema: import("./core.js").CompatibleRespon
                 unmonitored: "unmonitored";
             }>>;
         }, z.core.$strip>>;
+        page: z.ZodOptional<z.ZodObject<{
+            readonly total: z.ZodNumber;
+            readonly limit: z.ZodNumber;
+            readonly offset: z.ZodNumber;
+            readonly hasMore: z.ZodBoolean;
+        }, z.core.$strip>>;
         total: z.ZodNumber;
         coverage: z.ZodEnum<{
             "issues-open": "issues-open";
@@ -276,6 +293,12 @@ export declare const pageInspectResponseSchema: import("./core.js").CompatibleRe
                     unmonitored: "unmonitored";
                 }>>;
             }, z.core.$strip>>;
+            page: z.ZodObject<{
+                readonly total: z.ZodNumber;
+                readonly limit: z.ZodNumber;
+                readonly offset: z.ZodNumber;
+                readonly hasMore: z.ZodBoolean;
+            }, z.core.$strip>;
             total: z.ZodNumber;
             coverage: z.ZodEnum<{
                 "issues-open": "issues-open";
@@ -348,6 +371,12 @@ export declare const pageInspectResponseSchema: import("./core.js").CompatibleRe
                     unmonitored: "unmonitored";
                 }>>;
             }, z.core.$strip>>;
+            page: z.ZodOptional<z.ZodObject<{
+                readonly total: z.ZodNumber;
+                readonly limit: z.ZodNumber;
+                readonly offset: z.ZodNumber;
+                readonly hasMore: z.ZodBoolean;
+            }, z.core.$strip>>;
             total: z.ZodNumber;
             coverage: z.ZodEnum<{
                 "issues-open": "issues-open";
@@ -480,6 +509,11 @@ export declare const pageScanResponseSchema: import("./core.js").CompatibleRespo
 }, z.core.$strip>>;
 export type PageInspectQuery = z.output<typeof pageInspectQuerySchema>;
 export type PageInspect = z.output<typeof pageInspectDataSchema.producer>;
+/**
+ * What a consumer receives. Additive fields are optional here, so a client
+ * newer than the deployed server still parses its answers.
+ */
+export type PageInspectData = z.output<typeof pageInspectDataSchema.client>;
 export type PageScanBody = z.output<typeof pageScanBodySchema>;
 export type PageScan = z.output<typeof pageScanDataSchema.producer>;
 export declare const pageInspectOperation: {
@@ -548,6 +582,12 @@ export declare const pageInspectOperation: {
                             unmonitored: "unmonitored";
                         }>>;
                     }, z.core.$strip>>;
+                    page: z.ZodObject<{
+                        readonly total: z.ZodNumber;
+                        readonly limit: z.ZodNumber;
+                        readonly offset: z.ZodNumber;
+                        readonly hasMore: z.ZodBoolean;
+                    }, z.core.$strip>;
                     total: z.ZodNumber;
                     coverage: z.ZodEnum<{
                         "issues-open": "issues-open";
@@ -620,6 +660,12 @@ export declare const pageInspectOperation: {
                             unmonitored: "unmonitored";
                         }>>;
                     }, z.core.$strip>>;
+                    page: z.ZodOptional<z.ZodObject<{
+                        readonly total: z.ZodNumber;
+                        readonly limit: z.ZodNumber;
+                        readonly offset: z.ZodNumber;
+                        readonly hasMore: z.ZodBoolean;
+                    }, z.core.$strip>>;
                     total: z.ZodNumber;
                     coverage: z.ZodEnum<{
                         "issues-open": "issues-open";
@@ -760,6 +806,12 @@ export declare const pageInspectOperation: {
                         };
                         readonly observations: {
                             readonly rows: readonly [];
+                            readonly page: {
+                                readonly total: 0;
+                                readonly limit: 100;
+                                readonly offset: 0;
+                                readonly hasMore: false;
+                            };
                             readonly total: 0;
                             readonly coverage: 'never-scanned';
                             readonly pagination: {
@@ -1804,6 +1856,12 @@ export declare const pagesV1Registry: import("./core.js").PublicV1Registry<{
                                 unmonitored: "unmonitored";
                             }>>;
                         }, z.core.$strip>>;
+                        page: z.ZodObject<{
+                            readonly total: z.ZodNumber;
+                            readonly limit: z.ZodNumber;
+                            readonly offset: z.ZodNumber;
+                            readonly hasMore: z.ZodBoolean;
+                        }, z.core.$strip>;
                         total: z.ZodNumber;
                         coverage: z.ZodEnum<{
                             "issues-open": "issues-open";
@@ -1876,6 +1934,12 @@ export declare const pagesV1Registry: import("./core.js").PublicV1Registry<{
                                 unmonitored: "unmonitored";
                             }>>;
                         }, z.core.$strip>>;
+                        page: z.ZodOptional<z.ZodObject<{
+                            readonly total: z.ZodNumber;
+                            readonly limit: z.ZodNumber;
+                            readonly offset: z.ZodNumber;
+                            readonly hasMore: z.ZodBoolean;
+                        }, z.core.$strip>>;
                         total: z.ZodNumber;
                         coverage: z.ZodEnum<{
                             "issues-open": "issues-open";
@@ -2016,6 +2080,12 @@ export declare const pagesV1Registry: import("./core.js").PublicV1Registry<{
                             };
                             readonly observations: {
                                 readonly rows: readonly [];
+                                readonly page: {
+                                    readonly total: 0;
+                                    readonly limit: 100;
+                                    readonly offset: 0;
+                                    readonly hasMore: false;
+                                };
                                 readonly total: 0;
                                 readonly coverage: 'never-scanned';
                                 readonly pagination: {

package/dist/v1/pages.js

@@ -1,5 +1,5 @@
 import { z as schema } from 'zod';
-import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1BooleanFlag, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
+import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1BooleanFlag, publicV1ErrorEnvelope, publicV1PageSchema, publicV1StandardRatePolicy, } from './core.js';
 export const pageSiteParamsSchema = schema.strictObject({
     siteId: schema.string().min(1),
 });
@@ -37,6 +37,11 @@ export const pageObservationSchema = defineResponseObject({
     resolvedAt: schema.string().datetime().nullable(),
     resolution: schema.enum(['fixed', 'removed', 'excluded', 'unmonitored', 'expired']).nullable(),
 });
+/**
+ * The latest Lighthouse Scan for one page. The four category scores run from 0
+ * to 100. `lcp` and `tbt` are milliseconds. `cls` is the unitless Cumulative
+ * Layout Shift value at the Lighthouse scale, so `0.1` is the "good" threshold.
+ */
 export const pageLighthouseSchema = defineResponseObject({
     scanId: schema.string().min(1),
     strategy: schema.enum(['mobile', 'desktop']),
@@ -86,8 +91,16 @@ export const pageInspectDataSchema = defineResponseObject({
     }),
     observations: schema.strictObject({
         rows: schema.array(pageObservationSchema.producer),
+        /**
+         * The converged list envelope. `data.page` already names the inspected
+         * Page here, so the list envelope sits beside its own `rows`.
+         */
+        page: publicV1PageSchema.producer,
         total: schema.number().int().nonnegative(),
         coverage: pageObservationCoverageSchema,
+        /**
+         * Deprecated alias of `page`. Kept for one minor version, then removed.
+         */
         pagination: schema.strictObject({
             limit: schema.number().int().positive(),
             offset: schema.number().int().nonnegative(),
@@ -107,6 +120,7 @@ export const pageInspectDataSchema = defineResponseObject({
     }),
     observations: schema.looseObject({
         rows: schema.array(pageObservationSchema.client),
+        page: publicV1PageSchema.client.optional(),
         total: schema.number().int().nonnegative(),
         coverage: pageObservationCoverageSchema,
         pagination: schema.looseObject({
@@ -200,6 +214,7 @@ export const pageInspectOperation = defineOperation({
                             page: { url: 'https://example.com/guide', path: '/guide' },
                             observations: {
                                 rows: [],
+                                page: { total: 0, limit: 100, offset: 0, hasMore: false },
                                 total: 0,
                                 coverage: 'never-scanned',
                                 pagination: { limit: 100, offset: 0, hasMore: false },

package/dist/v1/performance.d.ts

@@ -35,6 +35,12 @@ export declare const performanceVitalSummarySchema: import("./core.js").Compatib
         poor: z.ZodNumber;
     }, z.core.$loose>;
 }, z.core.$strip>>;
+/**
+ * Medians across the Site's latest Scans. Units follow the field: `perf`,
+ * `a11y`, `bestPractices` and `seo` are scores from 0 to 100, `lcp` and `tbt`
+ * are milliseconds, and `cls` is the unitless Cumulative Layout Shift value.
+ * `statusCounts` counts Scans in the good, needs-improvement and poor bands.
+ */
 export declare const sitePerformanceHealthSchema: import("./core.js").CompatibleResponseSchema<z.ZodObject<{
     readonly perf: z.ZodObject<{
         readonly median: z.ZodNullable<z.ZodNumber>;
@@ -962,8 +968,8 @@ export declare const sitePerformanceOverviewOperation: {
                                 };
                             };
                             readonly cls: {
-                                readonly median: 80;
-                                readonly worst: 260;
+                                readonly median: 0.08;
+                                readonly worst: 0.26;
                                 readonly statusCounts: {
                                     readonly good: 4;
                                     readonly ni: 0;
@@ -3739,8 +3745,8 @@ export declare const performanceV1Registry: import("./core.js").PublicV1Registry
                                     };
                                 };
                                 readonly cls: {
-                                    readonly median: 80;
-                                    readonly worst: 260;
+                                    readonly median: 0.08;
+                                    readonly worst: 0.26;
                                     readonly statusCounts: {
                                         readonly good: 4;
                                         readonly ni: 0;

package/dist/v1/performance.js

@@ -4,6 +4,19 @@ export const performanceSiteParamsSchema = schema.strictObject({
     siteId: schema.string().min(1),
 });
 const nullableMetricSchema = schema.number().nullable();
+/**
+ * A Lighthouse category score, 0 to 100, where a higher number is better.
+ * Used for `perf`, `a11y`, `bestPractices` and `seo`.
+ */
+const nullableScoreSchema = nullableMetricSchema;
+/** A measured duration in milliseconds. Used for `lcp` and `tbt`. */
+const nullableMillisecondsSchema = nullableMetricSchema;
+/**
+ * Cumulative Layout Shift, unitless, normally between 0 and about 1. A lower
+ * number is better. Reported at the same scale as Lighthouse reports it, so
+ * `0.1` is the "good" threshold, not `100`.
+ */
+const nullableLayoutShiftSchema = nullableMetricSchema;
 export const performanceScoreSummarySchema = defineResponseObject({
     median: nullableMetricSchema,
     worst: nullableMetricSchema,
@@ -37,6 +50,12 @@ export const performanceVitalSummarySchema = defineResponseObject({
         poor: schema.number().int().nonnegative(),
     }),
 });
+/**
+ * Medians across the Site's latest Scans. Units follow the field: `perf`,
+ * `a11y`, `bestPractices` and `seo` are scores from 0 to 100, `lcp` and `tbt`
+ * are milliseconds, and `cls` is the unitless Cumulative Layout Shift value.
+ * `statusCounts` counts Scans in the good, needs-improvement and poor bands.
+ */
 export const sitePerformanceHealthSchema = defineResponseObject({
     perf: performanceScoreSummarySchema.producer,
     a11y: performanceCategorySummarySchema.producer,
@@ -62,24 +81,24 @@ 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,
+    perf: nullableScoreSchema,
+    a11y: nullableScoreSchema,
+    bestPractices: nullableScoreSchema,
+    seo: nullableScoreSchema,
+    lcp: nullableMillisecondsSchema,
+    tbt: nullableMillisecondsSchema,
+    cls: nullableLayoutShiftSchema,
 }, {
     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,
+    perf: nullableScoreSchema,
+    a11y: nullableScoreSchema,
+    bestPractices: nullableScoreSchema,
+    seo: nullableScoreSchema,
+    lcp: nullableMillisecondsSchema,
+    tbt: nullableMillisecondsSchema,
+    cls: nullableLayoutShiftSchema,
 });
 export const sitePerformanceRouteSchema = defineResponseObject({
     pageId: schema.string().min(1),
@@ -87,26 +106,26 @@ export const sitePerformanceRouteSchema = defineResponseObject({
     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,
+    perf: nullableScoreSchema,
+    a11y: nullableScoreSchema,
+    bestPractices: nullableScoreSchema,
+    seo: nullableScoreSchema,
+    lcp: nullableMillisecondsSchema,
+    tbt: nullableMillisecondsSchema,
+    cls: nullableLayoutShiftSchema,
 }, {
     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,
+    perf: nullableScoreSchema,
+    a11y: nullableScoreSchema,
+    bestPractices: nullableScoreSchema,
+    seo: nullableScoreSchema,
+    lcp: nullableMillisecondsSchema,
+    tbt: nullableMillisecondsSchema,
+    cls: nullableLayoutShiftSchema,
 });
 export const sitePerformanceOverviewDataSchema = defineResponseObject({
     health: sitePerformanceHealthSchema.producer.nullable(),
@@ -175,7 +194,7 @@ export const sitePerformanceOverviewOperation = defineOperation({
                                 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 } },
+                                cls: { median: 0.08, worst: 0.26, statusCounts: { good: 4, ni: 0, poor: 1 } },
                                 scannedPageCount: 5,
                                 lastScanAt: '2026-08-10T01:00:00.000Z',
                             },