@nuxtseo/protocol 0.1.4 → 0.2.0

package/dist/v1/gsc.js

@@ -15,6 +15,31 @@ export const searchAnalyticsViewSchema = schema.enum([
     'analysis',
 ]);
 const periodSchema = schema.enum(['7d', '28d', '3m', '6m', '12m']);
+/**
+ * Legacy response discriminator alias. This operation shipped in 1.0.0 with
+ * its response objects discriminating on `type`; v1 clients generated from
+ * that contract still key on it. Producers keep emitting `type` alongside the
+ * canonical `view` for one deprecation window instead of breaking them
+ * implicitly within the same major version.
+ */
+function legacyViewDiscriminator(view) {
+    return schema.literal(view).default(view);
+}
+/**
+ * Accept envelopes keyed by either spelling: a payload carrying only the
+ * legacy `type` gains the canonical `view` before the discriminated union
+ * parses it.
+ */
+function acceptLegacyViewDiscriminator(union) {
+    return schema.preprocess((value) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return value;
+        const candidate = value;
+        if (!('view' in candidate) && typeof candidate.type === 'string')
+            return { ...candidate, view: candidate.type };
+        return value;
+    }, union);
+}
 const pageUrlSchema = schema.string().refine(value => value.startsWith('/') || URL.canParse(value), 'Expected an absolute URL or a site-relative path starting with /.');
 export const searchAnalyticsQuerySchema = schema.strictObject({
     view: searchAnalyticsViewSchema,
@@ -92,7 +117,8 @@ const deviceRowSchema = defineResponseObject({
 function breakdownSchema(view, row) {
     return defineResponseObject({
         site: schema.string().min(1),
-        type: schema.literal(view),
+        view: schema.literal(view),
+        type: legacyViewDiscriminator(view),
         period: periodSchema,
         total: schema.number().int().nonnegative(),
         totals: totalsSchema.producer.nullable(),
@@ -102,7 +128,7 @@ function breakdownSchema(view, row) {
         rows: schema.array(row.producer),
     }, {
         site: schema.string().min(1),
-        type: schema.literal(view),
+        view: schema.literal(view),
         period: periodSchema,
         total: schema.number().int().nonnegative(),
         totals: totalsSchema.client.nullable(),
@@ -125,14 +151,15 @@ const dailyRowSchema = defineResponseObject({
 });
 const timeseriesDataSchema = defineResponseObject({
     site: schema.string().min(1),
-    type: schema.literal('timeseries'),
+    view: schema.literal('timeseries'),
+    type: legacyViewDiscriminator('timeseries'),
     period: periodSchema,
     totals: totalsSchema.producer.nullable(),
     prevTotals: totalsSchema.producer.nullable(),
     daily: schema.array(dailyRowSchema.producer),
 }, {
     site: schema.string().min(1),
-    type: schema.literal('timeseries'),
+    view: schema.literal('timeseries'),
     period: periodSchema,
     totals: totalsSchema.client.nullable(),
     prevTotals: totalsSchema.client.nullable(),
@@ -149,14 +176,15 @@ const pageDetailRowSchema = defineResponseObject({
 });
 const pageDetailDataSchema = defineResponseObject({
     site: schema.string().min(1),
-    type: schema.literal('page-detail'),
+    view: schema.literal('page-detail'),
+    type: legacyViewDiscriminator('page-detail'),
     pageUrl: pageUrlSchema,
     period: periodSchema,
     totals: totalsSchema.producer.nullable(),
     rows: schema.array(pageDetailRowSchema.producer),
 }, {
     site: schema.string().min(1),
-    type: schema.literal('page-detail'),
+    view: schema.literal('page-detail'),
     pageUrl: pageUrlSchema,
     period: periodSchema,
     totals: totalsSchema.client.nullable(),
@@ -173,14 +201,15 @@ const keywordDetailRowSchema = defineResponseObject({
 });
 const keywordDetailDataSchema = defineResponseObject({
     site: schema.string().min(1),
-    type: schema.literal('keyword-detail'),
+    view: schema.literal('keyword-detail'),
+    type: legacyViewDiscriminator('keyword-detail'),
     keyword: schema.string().min(1),
     period: periodSchema,
     totals: totalsSchema.producer.nullable(),
     rows: schema.array(keywordDetailRowSchema.producer),
 }, {
     site: schema.string().min(1),
-    type: schema.literal('keyword-detail'),
+    view: schema.literal('keyword-detail'),
     keyword: schema.string().min(1),
     period: periodSchema,
     totals: totalsSchema.client.nullable(),
@@ -205,7 +234,8 @@ const analysisRowSchema = defineResponseObject({
 });
 const analysisDataSchema = defineResponseObject({
     site: schema.string().min(1),
-    type: schema.literal('analysis'),
+    view: schema.literal('analysis'),
+    type: legacyViewDiscriminator('analysis'),
     preset: gscdumpAnalysisPresetSchema,
     description: schema.string().min(1),
     criteria: schema.record(schema.string(), schema.union([schema.string(), schema.number(), schema.null()])),
@@ -215,7 +245,7 @@ const analysisDataSchema = defineResponseObject({
     rows: schema.array(analysisRowSchema.producer),
 }, {
     site: schema.string().min(1),
-    type: schema.literal('analysis'),
+    view: schema.literal('analysis'),
     preset: gscdumpAnalysisPresetSchema,
     description: schema.string().min(1),
     criteria: schema.record(schema.string(), schema.union([schema.string(), schema.number(), schema.null()])),
@@ -225,7 +255,7 @@ const analysisDataSchema = defineResponseObject({
     rows: schema.array(analysisRowSchema.client),
 });
 export const searchAnalyticsDataSchema = {
-    producer: schema.discriminatedUnion('type', [
+    producer: schema.discriminatedUnion('view', [
         pagesDataSchema.producer,
         keywordsDataSchema.producer,
         countriesDataSchema.producer,
@@ -235,7 +265,7 @@ export const searchAnalyticsDataSchema = {
         keywordDetailDataSchema.producer,
         analysisDataSchema.producer,
     ]),
-    client: schema.discriminatedUnion('type', [
+    client: acceptLegacyViewDiscriminator(schema.discriminatedUnion('view', [
         pagesDataSchema.client,
         keywordsDataSchema.client,
         countriesDataSchema.client,
@@ -244,7 +274,7 @@ export const searchAnalyticsDataSchema = {
         pageDetailDataSchema.client,
         keywordDetailDataSchema.client,
         analysisDataSchema.client,
-    ]),
+    ])),
 };
 export const searchAnalyticsResponseSchema = defineSuccessEnvelope(searchAnalyticsDataSchema);
 export const searchStatusDataSchema = {
@@ -480,7 +510,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', type: '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 }] }, meta: { requestId: 'req_01JXYZ', version: '1.0' } } },
             }],
     },
 });
@@ -544,6 +574,194 @@ export const urlInspectionReadOperation = defineOperation({
         examples: [{ request: { params: { siteId: 'site_01JXYZ' }, query: { url: '/docs' } }, response: { status: 200, body: { data: { _tag: 'no-inspection-data', requestedUrl: 'https://example.com/docs' }, meta: { requestId: 'req_01JXYZ', version: '1.0' } } } }],
     },
 });
+export const indexCohortsQuerySchema = schema.strictObject({
+    limit: schema.coerce.number().int().min(1).max(50).default(12),
+    minSectionPages: schema.coerce.number().int().min(1).max(500).default(5),
+});
+export const establishedCohortSchema = defineResponseObject({
+    family: schema.string(),
+    dimension: schema.string(),
+    /**
+     * Null when the cohort is not expressible as one path prefix. Every
+     * `lifecycle` cohort is: version-pinned pages span the whole Site, so a
+     * drill-through must fall back to the unfiltered not-indexed list.
+     */
+    pathPrefix: schema.string().nullable(),
+    pages: schema.number().int().nonnegative(),
+    notIndexed: schema.number().int().nonnegative(),
+    notIndexedPercent: schema.number(),
+    restOfSitePercent: schema.number(),
+    restOfSitePages: schema.number().int().nonnegative(),
+    confidenceIntervalLower: schema.number(),
+    confidenceIntervalUpper: schema.number(),
+    /** Families nest, so subtract this before summing notIndexed down the list. */
+    alreadyCountedAbove: schema.number().int().nonnegative(),
+}, {
+    family: schema.string(),
+    dimension: schema.string(),
+    pathPrefix: schema.string().nullable(),
+    pages: schema.number().int().nonnegative(),
+    notIndexed: schema.number().int().nonnegative(),
+    notIndexedPercent: schema.number(),
+    restOfSitePercent: schema.number(),
+    restOfSitePages: schema.number().int().nonnegative(),
+    confidenceIntervalLower: schema.number(),
+    confidenceIntervalUpper: schema.number(),
+    alreadyCountedAbove: schema.number().int().nonnegative(),
+});
+export const rankedCohortSchema = defineResponseObject({
+    family: schema.string(),
+    pages: schema.number().int().nonnegative(),
+    notIndexed: schema.number().int().nonnegative(),
+    notIndexedPercent: schema.number(),
+    /** False means this family has NOT been shown to differ from the rest of the Site. */
+    statisticallyEstablished: schema.boolean(),
+    belowMinimumSample: schema.boolean(),
+}, {
+    family: schema.string(),
+    pages: schema.number().int().nonnegative(),
+    notIndexed: schema.number().int().nonnegative(),
+    notIndexedPercent: schema.number(),
+    statisticallyEstablished: schema.boolean(),
+    belowMinimumSample: schema.boolean(),
+});
+const cohortBaselineShape = {
+    pages: schema.number().int().nonnegative(),
+    notIndexed: schema.number().int().nonnegative(),
+    notIndexedPercent: schema.number(),
+};
+const cohortCoverageShape = {
+    analysed: schema.number().int().nonnegative(),
+    notIndexedButNeverCrawled: schema.number().int().nonnegative(),
+    excludedFragments: schema.number().int().nonnegative(),
+};
+/**
+ * Two lists that mean different things and must never be merged.
+ * `established` holds only families whose Wilson score interval clears the
+ * not-indexed rate of their own complement after a Bonferroni correction; those
+ * are the only rows that may be reported as a finding. `ranked` orders every
+ * family by raw rate with no test applied, so it always answers "where is
+ * indexing worst" — a high rate there is a lead to verify, never a conclusion.
+ */
+export const indexCohortsDataSchema = defineResponseObject({
+    analysed: schema.boolean(),
+    reason: schema.string().nullable(),
+    message: schema.string().nullable(),
+    asOf: schema.string().nullable(),
+    baseline: schema.strictObject(cohortBaselineShape).nullable(),
+    coverage: schema.strictObject(cohortCoverageShape).nullable(),
+    method: schema.string().nullable(),
+    familiesTested: schema.number().int().nonnegative(),
+    established: schema.array(establishedCohortSchema.producer),
+    establishedNote: schema.string().nullable(),
+    ranked: schema.array(rankedCohortSchema.producer),
+    rankedTotal: schema.number().int().nonnegative(),
+    minSectionPages: schema.number().int().positive(),
+}, {
+    analysed: schema.boolean(),
+    reason: schema.string().nullable(),
+    message: schema.string().nullable(),
+    asOf: schema.string().nullable(),
+    baseline: schema.looseObject(cohortBaselineShape).nullable(),
+    coverage: schema.looseObject(cohortCoverageShape).nullable(),
+    method: schema.string().nullable(),
+    familiesTested: schema.number().int().nonnegative(),
+    established: schema.array(establishedCohortSchema.client),
+    establishedNote: schema.string().nullable(),
+    ranked: schema.array(rankedCohortSchema.client),
+    rankedTotal: schema.number().int().nonnegative(),
+    minSectionPages: schema.number().int().positive(),
+});
+export const indexCohortsResponseEnvelopeSchema = defineSuccessEnvelope(indexCohortsDataSchema);
+export const indexCohortsReadOperation = defineOperation({
+    id: 'sites.search.indexing.cohorts.read',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/search/indexing/cohorts',
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'primary' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['sites:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: { params: searchConsoleSiteParamsSchema, query: indexCohortsQuerySchema, headers: null, body: null },
+    responses: { 200: indexCohortsResponseEnvelopeSchema },
+    // The same list every other Search read declares: this operation enforces the
+    // `search.collect_interactive` monitoring fence, whose denials present as
+    // `entitlement_required` and `conflict`.
+    // A pure D1 read: it cannot fail on a provider or on stale evidence, so it
+    // does not inherit this feature's shared read errors.
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'not_found',
+        'entitlement_required',
+        'conflict',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.collection', idFrom: 'params.siteId' }], changes: [] },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Read indexing by route family',
+        description: 'Returns the not-indexed rate per route family, joined from the Site crawl to Google per-URL index state, so an indexing failure that clusters in one template surfaces as one finding instead of many page-level ones. Read it before listing individual not-indexed URLs. `established` holds only families proven worse than the rest of the Site after a Bonferroni correction; `ranked` orders every family by raw rate with no test applied and is leads only. `analysed: false` means there is no completed crawl or no index state to join, which is not the same as healthy indexing.',
+        tags: ['Search Console'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { limit: 12, minSectionPages: 5 } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            analysed: true,
+                            reason: null,
+                            message: null,
+                            asOf: '2026-09-01T00:00:00.000Z',
+                            baseline: { pages: 1200, notIndexed: 180, notIndexedPercent: 15 },
+                            coverage: { analysed: 1200, notIndexedButNeverCrawled: 40, excludedFragments: 2 },
+                            method: 'Wilson score interval per family against its own complement, Bonferroni-corrected across 9 tested families (critical value z=2.77).',
+                            familiesTested: 9,
+                            established: [{
+                                    family: '/docs',
+                                    dimension: 'depth-1',
+                                    pathPrefix: '/docs',
+                                    pages: 420,
+                                    notIndexed: 150,
+                                    notIndexedPercent: 35.7,
+                                    restOfSitePercent: 3.8,
+                                    restOfSitePages: 780,
+                                    confidenceIntervalLower: 31.2,
+                                    confidenceIntervalUpper: 40.4,
+                                    alreadyCountedAbove: 0,
+                                }],
+                            establishedNote: null,
+                            ranked: [{
+                                    family: '/docs',
+                                    pages: 420,
+                                    notIndexed: 150,
+                                    notIndexedPercent: 35.7,
+                                    statisticallyEstablished: true,
+                                    belowMinimumSample: false,
+                                }],
+                            rankedTotal: 9,
+                            minSectionPages: 5,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
 export const searchV1Registry = defineRegistry({
     feature: 'sites',
     operations: {
@@ -552,5 +770,6 @@ export const searchV1Registry = defineRegistry({
         readIndexingDiagnostics: indexingDiagnosticsReadOperation,
         readIndexingHistory: indexingHistoryReadOperation,
         readUrlInspection: urlInspectionReadOperation,
+        readIndexingCohorts: indexCohortsReadOperation,
     },
 });