@nuxtseo/protocol 0.1.0

package/dist/v1/pages.js

@@ -0,0 +1,287 @@
+import { z as schema } from 'zod';
+import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
+export const pageSiteParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+});
+export const pageInspectQuerySchema = schema.strictObject({
+    url: schema.string().url(),
+    includeResolved: schema.enum(['0', '1', 'true', 'false']).default('0').transform(value => value === '1' || value === 'true'),
+    limit: schema.coerce.number().int().min(1).max(200).default(100),
+    offset: schema.coerce.number().int().min(0).default(0),
+});
+export const pageScanBodySchema = schema.strictObject({
+    url: schema.string().url(),
+});
+export const pageObservationSchema = defineResponseObject({
+    url: schema.string().url(),
+    path: schema.string(),
+    pathWithQuery: schema.string(),
+    source: schema.string().min(1),
+    issueType: schema.string().min(1),
+    severity: schema.enum(['error', 'warning', 'info']),
+    detail: schema.record(schema.string(), schema.unknown()).nullable(),
+    firstSeenAt: schema.string().datetime().nullable(),
+    lastSeenAt: schema.string().datetime().nullable(),
+    resolvedAt: schema.string().datetime().nullable(),
+    resolution: schema.enum(['fixed', 'removed', 'excluded', 'unmonitored']).nullable(),
+}, {
+    url: schema.string().url(),
+    path: schema.string(),
+    pathWithQuery: schema.string(),
+    source: schema.string().min(1),
+    issueType: schema.string().min(1),
+    severity: schema.enum(['error', 'warning', 'info']),
+    detail: schema.record(schema.string(), schema.unknown()).nullable(),
+    firstSeenAt: schema.string().datetime().nullable(),
+    lastSeenAt: schema.string().datetime().nullable(),
+    resolvedAt: schema.string().datetime().nullable(),
+    resolution: schema.enum(['fixed', 'removed', 'excluded', 'unmonitored']).nullable(),
+});
+export const pageLighthouseSchema = defineResponseObject({
+    scanId: schema.string().min(1),
+    strategy: schema.enum(['mobile', 'desktop']),
+    completedAt: schema.string().datetime().nullable(),
+    performance: schema.number().nullable(),
+    accessibility: schema.number().nullable(),
+    bestPractices: schema.number().nullable(),
+    seo: schema.number().nullable(),
+    lcp: schema.number().nullable(),
+    tbt: schema.number().nullable(),
+    cls: schema.number().nullable(),
+}, {
+    scanId: schema.string().min(1),
+    strategy: schema.enum(['mobile', 'desktop']),
+    completedAt: schema.string().datetime().nullable(),
+    performance: schema.number().nullable(),
+    accessibility: schema.number().nullable(),
+    bestPractices: schema.number().nullable(),
+    seo: schema.number().nullable(),
+    lcp: schema.number().nullable(),
+    tbt: schema.number().nullable(),
+    cls: schema.number().nullable(),
+});
+export const pageRankingKeywordSchema = defineResponseObject({
+    keyword: schema.string().min(1),
+    volume: schema.number().nullable(),
+    position: schema.number().nullable(),
+    checkedAt: schema.string().datetime().nullable(),
+}, {
+    keyword: schema.string().min(1),
+    volume: schema.number().nullable(),
+    position: schema.number().nullable(),
+    checkedAt: schema.string().datetime().nullable(),
+});
+export const pageInspectDataSchema = defineResponseObject({
+    page: schema.strictObject({
+        url: schema.string().url(),
+        path: schema.string(),
+    }),
+    observations: schema.strictObject({
+        rows: schema.array(pageObservationSchema.producer),
+        total: schema.number().int().nonnegative(),
+        pagination: schema.strictObject({
+            limit: schema.number().int().positive(),
+            offset: schema.number().int().nonnegative(),
+            hasMore: schema.boolean(),
+        }),
+    }),
+    performance: schema.strictObject({
+        lighthouse: pageLighthouseSchema.producer.nullable(),
+    }),
+    search: schema.strictObject({
+        keywords: schema.array(pageRankingKeywordSchema.producer),
+    }),
+}, {
+    page: schema.looseObject({
+        url: schema.string().url(),
+        path: schema.string(),
+    }),
+    observations: schema.looseObject({
+        rows: schema.array(pageObservationSchema.client),
+        total: schema.number().int().nonnegative(),
+        pagination: schema.looseObject({
+            limit: schema.number().int().positive(),
+            offset: schema.number().int().nonnegative(),
+            hasMore: schema.boolean(),
+        }),
+    }),
+    performance: schema.looseObject({
+        lighthouse: pageLighthouseSchema.client.nullable(),
+    }),
+    search: schema.looseObject({
+        keywords: schema.array(pageRankingKeywordSchema.client),
+    }),
+});
+export const pageInspectResponseSchema = defineSuccessEnvelope(pageInspectDataSchema);
+export const pageScanItemSchema = defineResponseObject({
+    scanId: schema.string().min(1),
+    pageId: schema.string().min(1),
+    url: schema.string().url(),
+    strategy: schema.enum(['mobile', 'desktop']),
+}, {
+    scanId: schema.string().min(1),
+    pageId: schema.string().min(1),
+    url: schema.string().url(),
+    strategy: schema.enum(['mobile', 'desktop']),
+});
+export const pageScanDataSchema = defineResponseObject({
+    pageId: schema.string().min(1),
+    pageCreated: schema.boolean(),
+    scanId: schema.string().min(1),
+    status: schema.literal('running'),
+    scans: schema.array(pageScanItemSchema.producer),
+}, {
+    pageId: schema.string().min(1),
+    pageCreated: schema.boolean(),
+    scanId: schema.string().min(1),
+    status: schema.literal('running'),
+    scans: schema.array(pageScanItemSchema.client),
+});
+export const pageScanResponseSchema = defineSuccessEnvelope(pageScanDataSchema);
+export const pageInspectOperation = defineOperation({
+    id: 'page.inspect',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/pages/inspect',
+    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: pageInspectQuerySchema, headers: null, body: null },
+    responses: { 200: pageInspectResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        '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.0.0' },
+    docs: {
+        summary: 'Inspect a Page',
+        description: 'Returns the current stored crawl, indexing, Lighthouse, and tracked ranking observations for one Page on the Site origin.',
+        tags: ['Pages'],
+        examples: [{
+                request: {
+                    params: { siteId: 'site_01JXYZ' },
+                    query: { url: 'https://example.com/guide', includeResolved: '0', limit: 100, offset: 0 },
+                },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            page: { url: 'https://example.com/guide', path: '/guide' },
+                            observations: {
+                                rows: [],
+                                total: 0,
+                                pagination: { limit: 100, offset: 0, hasMore: false },
+                            },
+                            performance: { lighthouse: null },
+                            search: { keywords: [] },
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const pageScanOperation = defineOperation({
+    id: 'page.scan',
+    method: 'POST',
+    path: '/api/v1/sites/{siteId}/pages/scan',
+    visibility: 'public',
+    semantics: { kind: 'mutation', sideEffects: 'state', retry: 'never', readConsistency: null },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['page:write'],
+        minimumRole: 'member',
+        ownership: 'site',
+    },
+    request: { params: pageSiteParamsSchema, query: null, headers: null, body: pageScanBodySchema },
+    responses: { 202: pageScanResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'entitlement_required',
+        'quota_exhausted',
+        'conflict',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: {
+        reads: [{ type: 'site.page', idFrom: 'params.siteId' }],
+        changes: [{ type: 'site.page', idFrom: 'params.siteId' }],
+    },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: 'growth',
+        meter: { key: 'lighthouse', units: 2, charge: 'live-only' },
+    },
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Scan a Page',
+        description: 'Ensures one Page is monitored and starts its mobile and desktop Lighthouse scans. This mutation is deliberately non-retryable because it can create monitoring and scan records.',
+        tags: ['Pages'],
+        examples: [{
+                request: {
+                    params: { siteId: 'site_01JXYZ' },
+                    body: { url: 'https://example.com/guide' },
+                },
+                response: {
+                    status: 202,
+                    body: {
+                        data: {
+                            pageId: 'page_01JXYZ',
+                            pageCreated: true,
+                            scanId: 'scan_mobile_01JXYZ',
+                            status: 'running',
+                            scans: [
+                                {
+                                    scanId: 'scan_mobile_01JXYZ',
+                                    pageId: 'page_01JXYZ',
+                                    url: 'https://example.com/guide',
+                                    strategy: 'mobile',
+                                },
+                                {
+                                    scanId: 'scan_desktop_01JXYZ',
+                                    pageId: 'page_01JXYZ',
+                                    url: 'https://example.com/guide',
+                                    strategy: 'desktop',
+                                },
+                            ],
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const pagesV1Registry = defineRegistry({
+    feature: 'page',
+    operations: {
+        inspect: pageInspectOperation,
+        scan: pageScanOperation,
+    },
+});