@nuxtseo/protocol 0.1.5 → 0.2.1

package/dist/v1/timeline.js

@@ -142,9 +142,253 @@ export const timelineEntriesOperation = defineOperation({
             }],
     },
 });
+// ---------------------------------------------------------------------------
+// Chart annotations — the date-anchored markers behind the `manage_annotations`
+// MCP tool. An agent that ships a fix marks the day it shipped, so the next
+// traffic or ranking move has a cause on the chart beside it.
+// ---------------------------------------------------------------------------
+/**
+ * A user-picked calendar day is a reporting-day bucket, never an instant
+ * (ADR-0082). It stays `YYYY-MM-DD` text so the marker lands on the chosen day
+ * in every timezone.
+ */
+export const annotationDaySchema = schema.iso.date();
+/** http(s) only: this value is rendered as a link in marker tooltips. */
+export const annotationLinkSchema = schema.string().url().max(500).refine(value => /^https?:\/\//i.test(value), { message: 'only http(s) URLs are allowed' });
+export const annotationParamsSchema = schema.strictObject({
+    siteId: schema.string().min(1),
+    annotationId: schema.string().min(1),
+});
+export const annotationCreateBodySchema = schema.strictObject({
+    date: annotationDaySchema,
+    title: schema.string().trim().min(1).max(120),
+    note: schema.string().trim().max(1000).nullish(),
+    url: annotationLinkSchema.nullish(),
+});
+export const annotationUpdateBodySchema = schema.strictObject({
+    date: annotationDaySchema.optional(),
+    title: schema.string().trim().min(1).max(120).optional(),
+    note: schema.string().trim().max(1000).nullish(),
+    url: annotationLinkSchema.nullish(),
+});
+export const annotationSchema = defineResponseObject({
+    id: schema.string().min(1),
+    date: schema.string().min(1),
+    title: schema.string(),
+    note: schema.string().nullable(),
+    url: schema.string().nullable(),
+}, {
+    id: schema.string().min(1),
+    date: schema.string().min(1),
+    title: schema.string(),
+    note: schema.string().nullable(),
+    url: schema.string().nullable(),
+});
+export const annotationListDataSchema = defineResponseObject({
+    annotations: schema.array(annotationSchema.producer),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+}, {
+    annotations: schema.array(annotationSchema.client),
+    total: schema.number().int().nonnegative(),
+    limit: schema.number().int().positive(),
+});
+export const annotationListResponseSchema = defineSuccessEnvelope(annotationListDataSchema);
+export const annotationDataSchema = defineResponseObject({ annotation: annotationSchema.producer }, { annotation: annotationSchema.client });
+export const annotationResponseSchema = defineSuccessEnvelope(annotationDataSchema);
+export const annotationDeleteDataSchema = defineResponseObject({ annotationId: schema.string().min(1), deleted: schema.literal(true) }, { annotationId: schema.string().min(1), deleted: schema.literal(true) });
+export const annotationDeleteResponseSchema = defineSuccessEnvelope(annotationDeleteDataSchema);
+const annotationReadErrors = [
+    'invalid_request',
+    'unauthorized',
+    'auth_expired',
+    'forbidden',
+    'not_found',
+    'rate_limited',
+    'contract_violation',
+    'internal_error',
+];
+const annotationWriteErrors = [
+    'invalid_request',
+    'unauthorized',
+    'auth_expired',
+    'forbidden',
+    'not_found',
+    'conflict',
+    'quota_exhausted',
+    'rate_limited',
+    'contract_violation',
+    'internal_error',
+];
+const annotationWriteAuth = {
+    credentials: ['session', 'api_token'],
+    scopes: ['timeline:write'],
+    minimumRole: 'member',
+    ownership: 'site',
+};
+const annotationWritePolicy = {
+    rate: publicV1StandardRatePolicy,
+    idempotency: { _tag: 'none' },
+    entitlement: null,
+    meter: null,
+};
+const annotationWriteResources = {
+    reads: [{ type: 'site.timeline', idFrom: 'params.siteId' }],
+    changes: [{ type: 'site.timeline', idFrom: 'params.siteId' }],
+};
+export const annotationListOperation = defineOperation({
+    id: 'timeline.annotations.list',
+    method: 'GET',
+    path: '/api/v1/sites/{siteId}/timeline/annotations',
+    visibility: 'public',
+    semantics: { kind: 'query', sideEffects: 'none', retry: 'idempotent', readConsistency: 'primary' },
+    auth: {
+        credentials: ['session', 'api_token'],
+        scopes: ['timeline:read'],
+        minimumRole: 'viewer',
+        ownership: 'site',
+    },
+    request: { params: timelineSiteParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: annotationListResponseSchema },
+    errors: annotationReadErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: { reads: [{ type: 'site.timeline', idFrom: 'params.siteId' }], changes: [] },
+    policy: {
+        rate: publicV1StandardRatePolicy,
+        idempotency: { _tag: 'none' },
+        entitlement: null,
+        meter: null,
+    },
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'List chart annotations',
+        description: 'Returns this Site own chart annotations, oldest day first. These are the markers a person or an agent placed; detected events and releases are read through the Timeline instead. `limit` is the per-Site cap, not a paging window.',
+        tags: ['Timeline'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: {
+                            annotations: [{
+                                    id: 'ann_01JXYZ',
+                                    date: '2026-07-30',
+                                    title: 'Shipped v3.2',
+                                    note: 'Canonical tags repaired across /docs',
+                                    url: 'https://github.com/owner/repo/releases/tag/v3.2.0',
+                                }],
+                            total: 1,
+                            limit: 100,
+                        },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const annotationCreateOperation = defineOperation({
+    id: 'timeline.annotations.create',
+    method: 'POST',
+    path: '/api/v1/sites/{siteId}/timeline/annotations',
+    visibility: 'public',
+    semantics: { kind: 'mutation', sideEffects: 'state', retry: 'never', readConsistency: null },
+    auth: annotationWriteAuth,
+    request: { params: timelineSiteParamsSchema, query: null, headers: null, body: annotationCreateBodySchema },
+    responses: { 200: annotationResponseSchema },
+    errors: annotationWriteErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: annotationWriteResources,
+    policy: annotationWritePolicy,
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Create a chart annotation',
+        description: 'Places one dated marker on this Site charts. Mark the day work shipped, so the next traffic or ranking move has a cause beside it. The Site has a fixed annotation cap; when it is reached the request is rejected and stale markers must be deleted first.',
+        tags: ['Timeline'],
+        examples: [{
+                request: {
+                    params: { siteId: 'site_01JXYZ' },
+                    body: { date: '2026-07-30', title: 'Shipped v3.2', note: null, url: null },
+                },
+                response: {
+                    status: 200,
+                    body: {
+                        data: { annotation: { id: 'ann_01JXYZ', date: '2026-07-30', title: 'Shipped v3.2', note: null, url: null } },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const annotationUpdateOperation = defineOperation({
+    id: 'timeline.annotations.update',
+    method: 'PATCH',
+    path: '/api/v1/sites/{siteId}/timeline/annotations/{annotationId}',
+    visibility: 'public',
+    semantics: { kind: 'mutation', sideEffects: 'state', retry: 'never', readConsistency: null },
+    auth: annotationWriteAuth,
+    request: { params: annotationParamsSchema, query: null, headers: null, body: annotationUpdateBodySchema },
+    responses: { 200: annotationResponseSchema },
+    errors: annotationWriteErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: annotationWriteResources,
+    policy: annotationWritePolicy,
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Update a chart annotation',
+        description: 'Changes the day, title, note, or link of one annotation. Send only the fields that change. Pass null for note or url to clear it.',
+        tags: ['Timeline'],
+        examples: [{
+                request: {
+                    params: { siteId: 'site_01JXYZ', annotationId: 'ann_01JXYZ' },
+                    body: { title: 'Shipped v3.2.1' },
+                },
+                response: {
+                    status: 200,
+                    body: {
+                        data: { annotation: { id: 'ann_01JXYZ', date: '2026-07-30', title: 'Shipped v3.2.1', note: null, url: null } },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
+export const annotationDeleteOperation = defineOperation({
+    id: 'timeline.annotations.delete',
+    method: 'DELETE',
+    path: '/api/v1/sites/{siteId}/timeline/annotations/{annotationId}',
+    visibility: 'public',
+    semantics: { kind: 'mutation', sideEffects: 'state', retry: 'never', readConsistency: null },
+    auth: annotationWriteAuth,
+    request: { params: annotationParamsSchema, query: null, headers: null, body: null },
+    responses: { 200: annotationDeleteResponseSchema },
+    errors: annotationWriteErrors,
+    errorResponse: publicV1ErrorEnvelope,
+    resources: annotationWriteResources,
+    policy: annotationWritePolicy,
+    lifecycle: { introduced: '1.2.0' },
+    docs: {
+        summary: 'Delete a chart annotation',
+        description: 'Removes one annotation permanently. Deleting frees a slot against the per-Site cap.',
+        tags: ['Timeline'],
+        examples: [{
+                request: { params: { siteId: 'site_01JXYZ', annotationId: 'ann_01JXYZ' } },
+                response: {
+                    status: 200,
+                    body: {
+                        data: { annotationId: 'ann_01JXYZ', deleted: true },
+                        meta: { requestId: 'req_01JXYZ', version: '1.0' },
+                    },
+                },
+            }],
+    },
+});
 export const timelineV1Registry = defineRegistry({
     feature: 'timeline',
     operations: {
         entries: timelineEntriesOperation,
+        listAnnotations: annotationListOperation,
+        createAnnotation: annotationCreateOperation,
+        updateAnnotation: annotationUpdateOperation,
+        deleteAnnotation: annotationDeleteOperation,
     },
 });