@nuxtseo/protocol 0.1.0

package/dist/v1/actions.js

@@ -0,0 +1,460 @@
+import { z as schema } from 'zod';
+import { defineOperation, defineRegistry, defineResponseObject, defineSuccessEnvelope, publicV1ErrorEnvelope, publicV1StandardRatePolicy, } from './core.js';
+export const actionSiteParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+});
+export const actionParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+    actionId: schema.string().min(1),
+});
+export const actionListQuerySchema = schema.strictObject({
+    limit: schema.coerce.number().int().min(1).max(25).default(10),
+    offset: schema.coerce.number().int().min(0).default(0),
+});
+export const actionShowQuerySchema = schema.strictObject({
+    groupId: schema.string().min(1).optional(),
+    cursor: schema.string().min(1).optional(),
+    limit: schema.coerce.number().int().min(1).max(100).default(50),
+});
+export const actionResolveBodySchema = schema.strictObject({
+    artifactVersion: schema.string().min(1),
+});
+export const actionSubjectSchema = defineResponseObject({
+    kind: schema.string().min(1),
+    label: schema.string().min(1),
+    url: schema.string().optional(),
+}, {
+    kind: schema.string().min(1),
+    label: schema.string().min(1),
+    url: schema.string().optional(),
+});
+export const actionSourceSchema = defineResponseObject({ label: schema.string().min(1), url: schema.string().url() }, { label: schema.string().min(1), url: schema.string().url() });
+export const actionEvidenceSummarySchema = defineResponseObject({
+    artifactVersion: schema.string().min(1).nullable(),
+    coverage: schema.enum(['complete', 'partial', 'count-only', 'unknown', 'unavailable']),
+    primaryKnownTotal: schema.number().int().nonnegative().nullable(),
+    knownTotal: schema.number().int().nonnegative(),
+    reportedTotal: schema.number().int().nonnegative().nullable(),
+    groupCount: schema.number().int().nonnegative(),
+    observedAt: schema.string().datetime().nullable(),
+    asOf: schema.string().datetime().nullable(),
+}, {
+    artifactVersion: schema.string().min(1).nullable(),
+    coverage: schema.enum(['complete', 'partial', 'count-only', 'unknown', 'unavailable']),
+    primaryKnownTotal: schema.number().int().nonnegative().nullable(),
+    knownTotal: schema.number().int().nonnegative(),
+    reportedTotal: schema.number().int().nonnegative().nullable(),
+    groupCount: schema.number().int().nonnegative(),
+    observedAt: schema.string().datetime().nullable(),
+    asOf: schema.string().datetime().nullable(),
+});
+export const actionListItemSchema = defineResponseObject({
+    id: schema.string().min(1),
+    status: schema.string().min(1),
+    diagnosis: schema.string().min(1),
+    subject: actionSubjectSchema.producer.nullable(),
+    source: actionSourceSchema.producer.nullable(),
+    authoredBy: schema.enum(['detector', 'agent']),
+    findingType: schema.string().min(1),
+    workLocation: schema.enum(['code', 'infra', 'off-site']),
+    effort: schema.enum(['S', 'M', 'L']),
+    affectedPages: schema.number().int().nonnegative().nullable(),
+    evidence: actionEvidenceSummarySchema.producer,
+    firstSeenAt: schema.string().datetime().nullable(),
+    relatedActionIds: schema.array(schema.string().min(1)),
+    resolution: schema.strictObject({
+        artifactVersion: schema.string().min(1),
+        evidenceScope: schema.enum(['complete', 'partial', 'count-only', 'unknown']),
+    }).nullable(),
+}, {
+    id: schema.string().min(1),
+    status: schema.string().min(1),
+    diagnosis: schema.string().min(1),
+    subject: actionSubjectSchema.client.nullable(),
+    source: actionSourceSchema.client.nullable(),
+    authoredBy: schema.enum(['detector', 'agent']),
+    findingType: schema.string().min(1),
+    workLocation: schema.enum(['code', 'infra', 'off-site']),
+    effort: schema.enum(['S', 'M', 'L']),
+    affectedPages: schema.number().int().nonnegative().nullable(),
+    evidence: actionEvidenceSummarySchema.client,
+    firstSeenAt: schema.string().datetime().nullable(),
+    relatedActionIds: schema.array(schema.string().min(1)),
+    resolution: schema.looseObject({
+        artifactVersion: schema.string().min(1),
+        evidenceScope: schema.enum(['complete', 'partial', 'count-only', 'unknown']),
+    }).nullable(),
+});
+export const actionListDataSchema = defineResponseObject({
+    actions: schema.array(actionListItemSchema.producer),
+    page: schema.strictObject({
+        total: schema.number().int().nonnegative(),
+        limit: schema.number().int().nonnegative(),
+        offset: schema.number().int().nonnegative(),
+        hasMore: schema.boolean(),
+    }),
+    listedAsOf: schema.string().datetime(),
+}, {
+    actions: schema.array(actionListItemSchema.client),
+    page: schema.looseObject({
+        total: schema.number().int().nonnegative(),
+        limit: schema.number().int().nonnegative(),
+        offset: schema.number().int().nonnegative(),
+        hasMore: schema.boolean(),
+    }),
+    listedAsOf: schema.string().datetime(),
+});
+export const actionListResponseSchema = defineSuccessEnvelope(actionListDataSchema);
+export const actionEvidenceCoverageSchema = schema.discriminatedUnion('_tag', [
+    schema.strictObject({ _tag: schema.literal('complete'), knownTotal: schema.number().int().nonnegative() }),
+    schema.strictObject({
+        _tag: schema.literal('partial'),
+        reportedTotal: schema.number().int().nonnegative(),
+        knownTotal: schema.number().int().nonnegative(),
+        limitation: schema.string().min(1),
+    }),
+    schema.strictObject({
+        _tag: schema.literal('count-only'),
+        reportedTotal: schema.number().int().nonnegative(),
+        limitation: schema.string().min(1),
+    }),
+    schema.strictObject({
+        _tag: schema.literal('unknown'),
+        knownTotal: schema.number().int().nonnegative(),
+        limitation: schema.string().min(1),
+    }),
+    schema.strictObject({ _tag: schema.literal('unavailable'), limitation: schema.string().min(1) }),
+]);
+export const actionEvidenceCoverageClientSchema = schema.discriminatedUnion('_tag', [
+    schema.looseObject({ _tag: schema.literal('complete'), knownTotal: schema.number().int().nonnegative() }),
+    schema.looseObject({
+        _tag: schema.literal('partial'),
+        reportedTotal: schema.number().int().nonnegative(),
+        knownTotal: schema.number().int().nonnegative(),
+        limitation: schema.string().min(1),
+    }),
+    schema.looseObject({
+        _tag: schema.literal('count-only'),
+        reportedTotal: schema.number().int().nonnegative(),
+        limitation: schema.string().min(1),
+    }),
+    schema.looseObject({
+        _tag: schema.literal('unknown'),
+        knownTotal: schema.number().int().nonnegative(),
+        limitation: schema.string().min(1),
+    }),
+    schema.looseObject({ _tag: schema.literal('unavailable'), limitation: schema.string().min(1) }),
+]);
+export const actionEvidenceItemSchema = schema.discriminatedUnion('_tag', [
+    schema.strictObject({
+        _tag: schema.literal('page-status'),
+        id: schema.string().min(1),
+        url: schema.string().url(),
+        status: schema.number().int(),
+    }),
+    schema.strictObject({
+        _tag: schema.literal('link-edge'),
+        id: schema.string().min(1),
+        sourceUrl: schema.string().url(),
+        targetUrl: schema.string().url(),
+        targetStatus: schema.number().int().nullable(),
+    }),
+    schema.strictObject({
+        _tag: schema.literal('provider-page'),
+        id: schema.string().min(1),
+        url: schema.string().url(),
+        reason: schema.string().min(1),
+        observedAt: schema.string().datetime().nullable(),
+    }),
+    schema.strictObject({
+        _tag: schema.literal('page'),
+        id: schema.string().min(1),
+        url: schema.string().url(),
+        detail: schema.string().nullable(),
+    }),
+]);
+export const actionEvidenceItemClientSchema = schema.discriminatedUnion('_tag', [
+    schema.looseObject({
+        _tag: schema.literal('page-status'),
+        id: schema.string().min(1),
+        url: schema.string().url(),
+        status: schema.number().int(),
+    }),
+    schema.looseObject({
+        _tag: schema.literal('link-edge'),
+        id: schema.string().min(1),
+        sourceUrl: schema.string().url(),
+        targetUrl: schema.string().url(),
+        targetStatus: schema.number().int().nullable(),
+    }),
+    schema.looseObject({
+        _tag: schema.literal('provider-page'),
+        id: schema.string().min(1),
+        url: schema.string().url(),
+        reason: schema.string().min(1),
+        observedAt: schema.string().datetime().nullable(),
+    }),
+    schema.looseObject({
+        _tag: schema.literal('page'),
+        id: schema.string().min(1),
+        url: schema.string().url(),
+        detail: schema.string().nullable(),
+    }),
+]);
+export const actionVerifierSchema = schema.discriminatedUnion('_tag', [
+    schema.strictObject({ _tag: schema.literal('target-healthy'), url: schema.string().url() }),
+    schema.strictObject({ _tag: schema.literal('finding-cleared'), findingType: schema.string().min(1) }),
+    schema.strictObject({ _tag: schema.literal('metric'), metric: schema.string().min(1) }),
+    schema.strictObject({ _tag: schema.literal('user-attested') }),
+]);
+export const actionVerifierClientSchema = schema.discriminatedUnion('_tag', [
+    schema.looseObject({ _tag: schema.literal('target-healthy'), url: schema.string().url() }),
+    schema.looseObject({ _tag: schema.literal('finding-cleared'), findingType: schema.string().min(1) }),
+    schema.looseObject({ _tag: schema.literal('metric'), metric: schema.string().min(1) }),
+    schema.looseObject({ _tag: schema.literal('user-attested') }),
+]);
+export const actionEvidenceGroupSchema = defineResponseObject({
+    id: schema.string().min(1),
+    relation: schema.string().min(1),
+    source: schema.strictObject({
+        kind: schema.string().min(1),
+        generationId: schema.string().min(1).nullable(),
+        observedAt: schema.string().datetime().nullable(),
+        collectedAt: schema.string().datetime(),
+    }),
+    coverage: actionEvidenceCoverageSchema,
+    items: schema.array(actionEvidenceItemSchema),
+    nextCursor: schema.string().nullable(),
+}, {
+    id: schema.string().min(1),
+    relation: schema.string().min(1),
+    source: schema.looseObject({
+        kind: schema.string().min(1),
+        generationId: schema.string().min(1).nullable(),
+        observedAt: schema.string().datetime().nullable(),
+        collectedAt: schema.string().datetime(),
+    }),
+    coverage: actionEvidenceCoverageClientSchema,
+    items: schema.array(actionEvidenceItemClientSchema),
+    nextCursor: schema.string().nullable(),
+});
+export const actionShowDataSchema = defineResponseObject({
+    id: schema.string().min(1),
+    status: schema.string().min(1),
+    findingType: schema.string().min(1),
+    artifactVersion: schema.string().min(1),
+    assessmentId: schema.string().min(1),
+    asOf: schema.string().datetime(),
+    diagnosis: schema.string().min(1),
+    action: schema.string().min(1),
+    verifier: actionVerifierSchema,
+    materiality: schema.strictObject({
+        affectedSubjects: schema.number().int().nonnegative(),
+        internalReferrers: schema.number().int().nonnegative(),
+    }),
+    evidenceGroups: schema.array(actionEvidenceGroupSchema.producer),
+}, {
+    id: schema.string().min(1),
+    status: schema.string().min(1),
+    findingType: schema.string().min(1),
+    artifactVersion: schema.string().min(1),
+    assessmentId: schema.string().min(1),
+    asOf: schema.string().datetime(),
+    diagnosis: schema.string().min(1),
+    action: schema.string().min(1),
+    verifier: actionVerifierClientSchema,
+    materiality: schema.looseObject({
+        affectedSubjects: schema.number().int().nonnegative(),
+        internalReferrers: schema.number().int().nonnegative(),
+    }),
+    evidenceGroups: schema.array(actionEvidenceGroupSchema.client),
+});
+export const actionShowResponseSchema = defineSuccessEnvelope(actionShowDataSchema);
+export const actionResolveDataSchema = defineResponseObject({
+    actionId: schema.string().min(1),
+    status: schema.string().min(1),
+    verification: schema.enum(['recheck-queued', 'scan-queued', 'next-assessment', 'metric-watch', 'user-resolved']),
+}, {
+    actionId: schema.string().min(1),
+    status: schema.string().min(1),
+    verification: schema.enum(['recheck-queued', 'scan-queued', 'next-assessment', 'metric-watch', 'user-resolved']),
+});
+export const actionResolveResponseSchema = defineSuccessEnvelope(actionResolveDataSchema);
+const actionReadSemantics = {
+    kind: 'query',
+    sideEffects: 'none',
+    retry: 'idempotent',
+    readConsistency: 'primary',
+};
+const actionReadAuth = {
+    credentials: ['session', 'api_token'],
+    scopes: ['actions:read'],
+    minimumRole: 'viewer',
+    ownership: 'site',
+};
+const actionReadErrors = [
+    'invalid_request',
+    'unauthorized',
+    'auth_expired',
+    'forbidden',
+    'entitlement_required',
+    'not_found',
+    'conflict',
+    'stale_evidence',
+    'rate_limited',
+    'provider_unavailable',
+    'contract_violation',
+    'internal_error',
+];
+const actionReadResources = {
+    reads: [{ type: 'site.actions', idFrom: 'params.siteId' }],
+    changes: [],
+};
+const actionReadPolicy = {
+    rate: publicV1StandardRatePolicy,
+    idempotency: { _tag: 'none' },
+    entitlement: null,
+    meter: null,
+};
+export const actionListOperation = defineOperation({
+    id: 'actions.list',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/actions',
+    visibility: 'public',
+    semantics: actionReadSemantics,
+    auth: actionReadAuth,
+    request: { params: actionSiteParamsSchema, query: actionListQuerySchema, headers: null, body: null },
+    responses: { 200: actionListResponseSchema },
+    errors: actionReadErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: actionReadResources,
+    policy: actionReadPolicy,
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'List next actions',
+        description: 'Returns the ranked open work for one site with stable evidence and resolution handles. Advisory movement signals remain separate from actionable work.',
+        tags: ['Actions'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' }, query: { limit: 10, offset: 0 } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            actions: [],
+                            page: { total: 0, limit: 0, offset: 0, hasMore: false },
+                            listedAsOf: '2026-08-10T01:30:00.000Z',
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const actionShowOperation = defineOperation({
+    id: 'actions.show',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/actions/{actionId}',
+    visibility: 'public',
+    semantics: actionReadSemantics,
+    auth: actionReadAuth,
+    request: { params: actionParamsSchema, query: actionShowQuerySchema, headers: null, body: null },
+    responses: { 200: actionShowResponseSchema },
+    errors: actionReadErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: actionReadResources,
+    policy: actionReadPolicy,
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Inspect an action',
+        description: 'Reads the versioned evidence reviewed before resolving an action. Evidence group cursors are bound to the artifact version.',
+        tags: ['Actions'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ', actionId: 'ticket_01JXYZ' }, query: { limit: 50 } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            id: 'ticket_01JXYZ',
+                            status: 'open',
+                            findingType: 'broken-pages',
+                            artifactVersion: 'te2:ticket_01JXYZ:scope',
+                            assessmentId: 'assessment_01JXYZ',
+                            asOf: '2026-08-10T01:30:00.000Z',
+                            diagnosis: 'One page returns HTTP 404.',
+                            action: 'Restore or redirect the page.',
+                            verifier: { _tag: 'finding-cleared', findingType: 'broken-pages' },
+                            materiality: { affectedSubjects: 1, internalReferrers: 2 },
+                            evidenceGroups: [],
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const actionResolveOperation = defineOperation({
+    id: 'actions.resolve',
+    method: 'POST',
+    path: '/api/v1/sites/{siteId}/actions/{actionId}/resolve',
+    visibility: 'public',
+    semantics: { kind: 'mutation', sideEffects: 'state', retry: 'never', readConsistency: null },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['actions:write'],
+        minimumRole: 'member',
+        ownership: 'site',
+    },
+    request: { params: actionParamsSchema, query: null, headers: null, body: actionResolveBodySchema },
+    responses: { 200: actionResolveResponseSchema },
+    errors: [
+        'invalid_request',
+        'unauthorized',
+        'auth_expired',
+        'forbidden',
+        'entitlement_required',
+        'not_found',
+        'stale_evidence',
+        'conflict',
+        'rate_limited',
+        'contract_violation',
+        'internal_error',
+    ],
+    errorResponse: publicV1ErrorEnvelope,
+    resources: {
+        reads: [{ type: 'site.actions', idFrom: 'params.siteId' }],
+        changes: [{ type: 'site.actions', idFrom: 'params.siteId' }],
+    },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.0.0' },
+    docs: {
+        summary: 'Resolve an action',
+        description: 'Claims a reviewed action against its exact evidence artifact and starts the authoritative verification path. This mutation is deliberately non-retryable because it writes claim clocks and events.',
+        tags: ['Actions'],
+        examples: [{
+                request: {
+                    params: { siteId: 'site_01JXYZ', actionId: 'ticket_01JXYZ' },
+                    body: { artifactVersion: 'te2:ticket_01JXYZ:scope' },
+                },
+                response: {
+                    status: 200,
+                    body: {
+                        data: { actionId: 'ticket_01JXYZ', status: 'open', verification: 'recheck-queued' },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const actionsV1Registry = defineRegistry({
+    feature: 'actions',
+    operations: {
+        list: actionListOperation,
+        show: actionShowOperation,
+        resolve: actionResolveOperation,
+    },
+});