@nuxtseo/protocol 0.1.4 → 0.2.0

package/dist/v1/sites.js

@@ -93,9 +93,239 @@ export const sitesListOperation = defineOperation({
             }],
     },
 });
+// ---------------------------------------------------------------------------
+// Site status — the flagship read behind the `site_status` MCP tool. One call
+// answers "what is wrong with this Site and what should I do first": the
+// assessment verdict, the single ranked Next Action, the worklist counts, the
+// recent changes, and the Receipts for work already verified.
+// ---------------------------------------------------------------------------
+export const siteStatusParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+});
+export const siteAssessmentSchema = defineResponseObject({
+    reachStage: schema.string().nullable(),
+    healthStage: schema.string().nullable(),
+    headlineAxis: schema.string().nullable(),
+    summary: schema.string(),
+    recommendation: schema.string(),
+    assessedAt: schema.string().datetime().nullable(),
+}, {
+    reachStage: schema.string().nullable(),
+    healthStage: schema.string().nullable(),
+    headlineAxis: schema.string().nullable(),
+    summary: schema.string(),
+    recommendation: schema.string(),
+    assessedAt: schema.string().datetime().nullable(),
+});
+/**
+ * The one ranked thing to do next. `kind` says what it is: `connect` asks for a
+ * missing data source, `action` points at a specific open Action by id, and
+ * `dimension` names an area with no single backing Action yet. Only `action`
+ * carries an `actionId` a caller can resolve.
+ */
+export const siteNextActionSchema = defineResponseObject({
+    kind: schema.enum(['connect', 'action', 'dimension']),
+    label: schema.string(),
+    detail: schema.string().nullable(),
+    focus: schema.string().nullable(),
+    dimension: schema.string().nullable(),
+    urgent: schema.boolean(),
+    /** Organic traffic at stake, the ranking magnitude. GLOSSARY: Impact. */
+    impact: schema.number().nullable(),
+    actionId: schema.string().nullable(),
+    citedProofKey: schema.string().nullable(),
+}, {
+    kind: schema.enum(['connect', 'action', 'dimension']),
+    label: schema.string(),
+    detail: schema.string().nullable(),
+    focus: schema.string().nullable(),
+    dimension: schema.string().nullable(),
+    urgent: schema.boolean(),
+    impact: schema.number().nullable(),
+    actionId: schema.string().nullable(),
+    citedProofKey: schema.string().nullable(),
+});
+export const siteStatusChangeSchema = defineResponseObject({
+    kind: schema.string(),
+    source: schema.string().nullable(),
+    label: schema.string(),
+    direction: schema.enum(['up', 'down', 'flat']),
+    value: schema.string().nullable(),
+    deltaPct: schema.number().nullable(),
+    window: schema.string().nullable(),
+    meaning: schema.string().nullable(),
+}, {
+    kind: schema.string(),
+    source: schema.string().nullable(),
+    label: schema.string(),
+    direction: schema.enum(['up', 'down', 'flat']),
+    value: schema.string().nullable(),
+    deltaPct: schema.number().nullable(),
+    window: schema.string().nullable(),
+    meaning: schema.string().nullable(),
+});
+export const siteStatusReceiptSchema = defineResponseObject({
+    actionId: schema.string().min(1),
+    title: schema.string(),
+    outcome: schema.string(),
+    observedAt: schema.string(),
+    note: schema.string().nullable(),
+}, {
+    actionId: schema.string().min(1),
+    title: schema.string(),
+    outcome: schema.string(),
+    observedAt: schema.string(),
+    note: schema.string().nullable(),
+});
+const siteStatusCountsShape = {
+    open: schema.number().int().nonnegative(),
+    inProgress: schema.number().int().nonnegative(),
+    shipped: schema.number().int().nonnegative(),
+    landed: schema.number().int().nonnegative(),
+    noEffect: schema.number().int().nonnegative(),
+};
+/**
+ * `dataQuality.status` is not decoration. `degraded` means the assessment ran
+ * with one or more proofs unavailable, so the verdict is real but incomplete;
+ * `unavailable` means it has not run at all. Read it before quoting the
+ * assessment as the Site's state.
+ */
+const siteStatusDataQualityShape = {
+    status: schema.enum(['complete', 'degraded', 'unavailable']),
+    reason: schema.string().nullable(),
+    unavailableProofs: schema.array(schema.string()),
+};
+export const siteStatusDataSchema = defineResponseObject({
+    site: schema.string(),
+    available: schema.boolean(),
+    message: schema.string().nullable(),
+    assessment: siteAssessmentSchema.producer.nullable(),
+    nextAction: siteNextActionSchema.producer.nullable(),
+    dataQuality: schema.strictObject(siteStatusDataQualityShape),
+    openCount: schema.number().int().nonnegative(),
+    verifiedCount: schema.number().int().nonnegative(),
+    counts: schema.strictObject(siteStatusCountsShape),
+    degradedSteps: schema.array(schema.string()),
+    changes: schema.array(siteStatusChangeSchema.producer),
+    receipts: schema.array(siteStatusReceiptSchema.producer),
+}, {
+    site: schema.string(),
+    available: schema.boolean(),
+    message: schema.string().nullable(),
+    assessment: siteAssessmentSchema.client.nullable(),
+    nextAction: siteNextActionSchema.client.nullable(),
+    dataQuality: schema.looseObject(siteStatusDataQualityShape),
+    openCount: schema.number().int().nonnegative(),
+    verifiedCount: schema.number().int().nonnegative(),
+    counts: schema.looseObject(siteStatusCountsShape),
+    degradedSteps: schema.array(schema.string()),
+    changes: schema.array(siteStatusChangeSchema.client),
+    receipts: schema.array(siteStatusReceiptSchema.client),
+});
+export const siteStatusResponseSchema = defineSuccessEnvelope(siteStatusDataSchema);
+export const siteStatusOperation = defineOperation({
+    id: 'sites.status',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/status',
+    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: siteStatusParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: siteStatusResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        // The Site monitoring fence this read enforces denies with these two:
+        // `entitlement_required` when the Site has no Pro Site access, `conflict` when
+        // it is archived or its collection is paused.
+        'entitlement_required',
+        'conflict',
+        'not_found',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.actions', idFrom: 'params.siteId' }], changes: [] },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Get Site status',
+        description: 'Returns the current assessment for one Site: the verdict, the single ranked Next Action, open and verified counts, the pipeline steps that degraded on the last run, recent changes, and recent Receipts. `available: false` means the first assessment has not run yet. Start here before listing Actions.',
+        tags: ['Sites'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            site: 'https://example.com',
+                            available: true,
+                            message: null,
+                            assessment: {
+                                reachStage: 'growing',
+                                healthStage: 'at-risk',
+                                headlineAxis: 'health',
+                                summary: 'Indexing is slipping on the docs template.',
+                                recommendation: 'Fix the canonical tag on /docs pages.',
+                                assessedAt: '2026-09-04T02:00:00.000Z',
+                            },
+                            nextAction: {
+                                kind: 'action',
+                                label: 'Fix indexing',
+                                detail: 'Repair the canonical tag on 42 /docs pages',
+                                focus: 'protect',
+                                dimension: 'indexing',
+                                urgent: true,
+                                impact: 1840,
+                                actionId: 'act_01JXYZ',
+                                citedProofKey: 'gsc.indexState',
+                            },
+                            dataQuality: { status: 'complete', reason: null, unavailableProofs: [] },
+                            openCount: 7,
+                            verifiedCount: 3,
+                            counts: { open: 5, inProgress: 2, shipped: 3, landed: 0, noEffect: 0 },
+                            degradedSteps: [],
+                            changes: [{
+                                    kind: 'indexing',
+                                    source: 'gsc',
+                                    label: 'Not-indexed pages rose to 42',
+                                    direction: 'up',
+                                    value: '42 pages',
+                                    deltaPct: 18.5,
+                                    window: '28d',
+                                    meaning: 'Google is declining more of this Site than last month.',
+                                }],
+                            receipts: [{
+                                    actionId: 'act_01JXYA',
+                                    title: 'Fixed: broken internal links in /guides',
+                                    outcome: 'verified',
+                                    observedAt: '2026-08-30',
+                                    note: null,
+                                }],
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
 export const sitesV1Registry = defineRegistry({
     feature: 'sites',
     operations: {
         list: sitesListOperation,
+        status: siteStatusOperation,
     },
 });