@nuxtseo/protocol 0.1.5 → 0.2.0

package/dist/v1/pages.js

@@ -289,10 +289,249 @@ export const pageScanOperation = defineOperation({
             }],
     },
 });
+// ---------------------------------------------------------------------------
+// Raw page observations — the read model behind the `page_issues` MCP tool.
+// This is the mutable observation store, never canonical Action membership:
+// read an Action with the Action operations for that. Select either one
+// Action's stamped keys (actionId) or one explicit source and issue pair.
+// ---------------------------------------------------------------------------
+export const pageIssuesQuerySchema = schema.strictObject({
+    actionId: schema.string().min(1).optional(),
+    source: schema.string().min(1).optional(),
+    issue: schema.string().min(1).optional(),
+    url: schema.string().min(1).optional(),
+    pathPrefix: schema.string().startsWith('/').optional(),
+    limit: schema.coerce.number().int().min(1).max(200).default(100),
+    offset: schema.coerce.number().int().min(0).default(0),
+    includeResolved: publicV1BooleanFlag(false),
+});
+const pageIssueTargetShape = {
+    url: schema.string().min(1),
+    status: schema.number().int().nullable(),
+};
+export const pageIssueTargetSchema = defineResponseObject(pageIssueTargetShape, pageIssueTargetShape);
+const pageIssueElementShape = {
+    selector: schema.string().nullable(),
+    snippet: schema.string().nullable(),
+    message: schema.string().nullable(),
+    explanation: schema.string().nullable(),
+    sourceUrl: schema.string().nullable(),
+};
+export const pageIssueElementSchema = defineResponseObject(pageIssueElementShape, pageIssueElementShape);
+/**
+ * `observedContentType` and `observedAt` are evidence, never a gate.
+ * `observedAt` dates a Search Console verdict: a fault fixed since that date is
+ * still reported here until Google re-inspects, so quote it as "as of", never
+ * as current. A null `observedContentType` means unknown, never `text/html`.
+ */
+export const pageIssueDetailSchema = defineResponseObject({
+    label: schema.string().nullable(),
+    resourceUrl: schema.string().nullable(),
+    statusCode: schema.number().int().nullable(),
+    targets: schema.array(pageIssueTargetSchema.producer),
+    isNew: schema.boolean().nullable(),
+    title: schema.string().nullable(),
+    description: schema.string().nullable(),
+    wcag: schema.array(schema.string()),
+    elements: schema.array(pageIssueElementSchema.producer),
+    elementsTotal: schema.number().int().nonnegative().nullable(),
+    observedContentType: schema.string().nullable(),
+    /**
+     * Whether the crawl recorded a content type for this row at all. It is the
+     * only way to read a null `observedContentType`: false means the crawl
+     * never captured one, true means it saw a response it could not name.
+     * Neither is `text/html`. The `page_issues` MCP tool carries the same
+     * distinction by omitting the key, so publishing the flag keeps the two
+     * surfaces answering the same question.
+     */
+    observedContentTypeCaptured: schema.boolean(),
+    redirectTarget: schema.string().nullable(),
+    observedAt: schema.string().nullable(),
+}, {
+    label: schema.string().nullable(),
+    resourceUrl: schema.string().nullable(),
+    statusCode: schema.number().int().nullable(),
+    targets: schema.array(pageIssueTargetSchema.client),
+    isNew: schema.boolean().nullable(),
+    title: schema.string().nullable(),
+    description: schema.string().nullable(),
+    wcag: schema.array(schema.string()),
+    elements: schema.array(pageIssueElementSchema.client),
+    elementsTotal: schema.number().int().nonnegative().nullable(),
+    observedContentType: schema.string().nullable(),
+    observedContentTypeCaptured: schema.boolean(),
+    redirectTarget: schema.string().nullable(),
+    observedAt: schema.string().nullable(),
+});
+/**
+ * `resolution` says WHY a closed row closed. `unmonitored` and `expired` mean
+ * nobody re-checked the page, so the defect may still be live; only a fixed row
+ * is evidence of a fix.
+ */
+export const pageIssueSchema = defineResponseObject({
+    url: schema.string().min(1),
+    path: schema.string(),
+    pathWithQuery: schema.string().nullable(),
+    source: schema.string().min(1),
+    issueType: schema.string().min(1),
+    severity: schema.string().min(1),
+    detail: pageIssueDetailSchema.producer,
+    firstSeenAt: schema.string().nullable(),
+    lastSeenAt: schema.string().nullable(),
+    resolution: schema.string().nullable(),
+    linkedFrom: schema.array(schema.string()),
+    linkedFromTotal: schema.number().int().nonnegative().nullable(),
+}, {
+    url: schema.string().min(1),
+    path: schema.string(),
+    pathWithQuery: schema.string().nullable(),
+    source: schema.string().min(1),
+    issueType: schema.string().min(1),
+    severity: schema.string().min(1),
+    detail: pageIssueDetailSchema.client,
+    firstSeenAt: schema.string().nullable(),
+    lastSeenAt: schema.string().nullable(),
+    resolution: schema.string().nullable(),
+    linkedFrom: schema.array(schema.string()),
+    linkedFromTotal: schema.number().int().nonnegative().nullable(),
+});
+const pageIssuesCoverageShape = {
+    perSourceCap: schema.number().int().positive(),
+    perRowTargetCap: schema.number().int().positive(),
+    perRowElementCap: schema.number().int().positive(),
+    possiblyTruncated: schema.boolean(),
+};
+export const pageIssuesDataSchema = defineResponseObject({
+    semantics: schema.literal('raw-observations'),
+    issues: schema.array(pageIssueSchema.producer),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+    offset: schema.number().int().nonnegative(),
+    /** Source and issue pairs this Site has, returned when the selector matched nothing. */
+    availableKeys: schema.array(schema.strictObject({
+        source: schema.string().min(1),
+        issue: schema.string().min(1),
+        openCount: schema.number().int().nonnegative(),
+    })).nullable(),
+    message: schema.string().nullable(),
+    asOf: schema.string().nullable(),
+    coverage: schema.strictObject(pageIssuesCoverageShape),
+}, {
+    semantics: schema.literal('raw-observations'),
+    issues: schema.array(pageIssueSchema.client),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+    offset: schema.number().int().nonnegative(),
+    availableKeys: schema.array(schema.looseObject({
+        source: schema.string().min(1),
+        issue: schema.string().min(1),
+        openCount: schema.number().int().nonnegative(),
+    })).nullable(),
+    message: schema.string().nullable(),
+    asOf: schema.string().nullable(),
+    coverage: schema.looseObject(pageIssuesCoverageShape),
+});
+export const pageIssuesResponseSchema = defineSuccessEnvelope(pageIssuesDataSchema);
+export const pageIssuesOperation = defineOperation({
+    id: 'page.issues',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/pages/issues',
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'primary' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['page:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: { params: pageSiteParamsSchema, query: pageIssuesQuerySchema, headers: null, body: null },
+    responses: { 200: pageIssuesResponseSchema },
+    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.page', idFrom: 'params.siteId' }], changes: [] },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Browse raw Page observations',
+        description: 'Returns raw page observations for one action id, or for one source and issue pair. Pass actionId, or pass both source and issue; passing both selectors is rejected. When the selector matches nothing, availableKeys lists the pairs this Site does have. These rows are the mutable observation store and never represent canonical action membership. Read coverage before quoting a total: storage retains at most 500 rows per source, and one request returns at most 200 rows, 8 targets, and 5 element samples per row.',
+        tags: ['Pages'],
+        examples: [{
+                request: {
+                    params: { siteId: 'site_01JXYZ' },
+                    query: { source: 'crawl', issue: 'broken-internal-links', limit: 100, offset: 0, includeResolved: '0' },
+                },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            semantics: 'raw-observations',
+                            issues: [{
+                                    url: 'https://example.com/docs/old',
+                                    path: '/docs/old',
+                                    pathWithQuery: null,
+                                    source: 'crawl',
+                                    issueType: 'broken-internal-links',
+                                    severity: 'error',
+                                    detail: {
+                                        label: 'Broken internal link',
+                                        resourceUrl: null,
+                                        statusCode: 404,
+                                        targets: [{ url: 'https://example.com/docs/new', status: 200 }],
+                                        isNew: true,
+                                        title: null,
+                                        description: null,
+                                        wcag: [],
+                                        elements: [],
+                                        elementsTotal: null,
+                                        observedContentType: 'text/html',
+                                        observedContentTypeCaptured: true,
+                                        redirectTarget: null,
+                                        observedAt: null,
+                                    },
+                                    firstSeenAt: '2026-08-01T00:00:00.000Z',
+                                    lastSeenAt: '2026-09-01T00:00:00.000Z',
+                                    resolution: null,
+                                    linkedFrom: ['https://example.com/docs/index'],
+                                    linkedFromTotal: 1,
+                                }],
+                            total: 1,
+                            limit: 100,
+                            offset: 0,
+                            availableKeys: null,
+                            message: null,
+                            asOf: null,
+                            coverage: { perSourceCap: 500, perRowTargetCap: 8, perRowElementCap: 5, possiblyTruncated: false },
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
 export const pagesV1Registry = defineRegistry({
     feature: 'page',
     operations: {
         inspect: pageInspectOperation,
         scan: pageScanOperation,
+        issues: pageIssuesOperation,
     },
 });