@nuxtseo/protocol 0.1.5 → 0.2.0

package/dist/v1/gsc.js

@@ -574,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: {
@@ -582,5 +770,6 @@ export const searchV1Registry = defineRegistry({
         readIndexingDiagnostics: indexingDiagnosticsReadOperation,
         readIndexingHistory: indexingHistoryReadOperation,
         readUrlInspection: urlInspectionReadOperation,
+        readIndexingCohorts: indexCohortsReadOperation,
     },
 });