@nuxtseo/protocol 0.1.0

package/dist/v1/core.js

@@ -0,0 +1,333 @@
+import { z } from 'zod';
+export const PUBLIC_V1_VERSION = '1.0';
+export const PUBLIC_V1_PATH_PREFIX = '/api/v1';
+export const PUBLIC_V1_RESPONSE_HEADERS = {
+    requestId: 'X-Request-Id',
+    version: 'X-NuxtSEO-Version',
+    operation: 'X-NuxtSEO-Operation',
+    rateLimitPolicy: 'RateLimit-Policy',
+    rateLimit: 'RateLimit',
+    retryAfter: 'Retry-After',
+    deprecation: 'Deprecation',
+    sunset: 'Sunset',
+};
+// Retain the existing authenticated Pro transport ceiling across supported adapters.
+// The public adapter partitions this quota by authoritative principal and
+// operation, so one expensive operation cannot starve unrelated reads.
+export const publicV1StandardRatePolicy = {
+    name: 'public-v1-fixed-window',
+    limit: 50,
+    windowSeconds: 60,
+};
+export const PUBLIC_V1_FEATURES = [
+    'account',
+    'actions',
+    'analytics',
+    'audit',
+    'backlinks',
+    'content',
+    'mentions',
+    'page',
+    'research',
+    'sites',
+];
+export const PUBLIC_V1_METHODS = ['DELETE', 'GET', 'PATCH', 'POST'];
+export const PUBLIC_V1_CREDENTIALS = ['api_token', 'session'];
+export const PUBLIC_V1_SCOPES = [
+    'account:read',
+    'actions:read',
+    'actions:write',
+    'analytics:read',
+    'audit:read',
+    'content:read',
+    'content:write',
+    'page:read',
+    'page:write',
+    'research:read',
+    'research:write',
+    'sites:read',
+    'sites:write',
+];
+export const PUBLIC_V1_ROLES = ['viewer', 'member', 'admin', 'owner'];
+export const PUBLIC_V1_ERROR_CODES = [
+    'invalid_request',
+    'unauthorized',
+    'forbidden',
+    'not_found',
+    'site_ambiguous',
+    'auth_expired',
+    'entitlement_required',
+    'quota_exhausted',
+    'provider_unavailable',
+    'stale_evidence',
+    'conflict',
+    'rate_limited',
+    'contract_violation',
+    'internal_error',
+];
+export const PUBLIC_V1_ERROR_STATUS = {
+    invalid_request: 400,
+    unauthorized: 401,
+    auth_expired: 401,
+    forbidden: 403,
+    entitlement_required: 403,
+    not_found: 404,
+    site_ambiguous: 409,
+    stale_evidence: 409,
+    conflict: 409,
+    quota_exhausted: 429,
+    rate_limited: 429,
+    contract_violation: 500,
+    internal_error: 500,
+    provider_unavailable: 503,
+};
+function pathParameterNames(path) {
+    return Array.from(path.matchAll(/\{([^{}]+)\}/g), match => match[1]);
+}
+function isSafePathTemplate(path) {
+    return /^\/api\/v1\/(?:[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?|\{[a-z][A-Za-z0-9]*\})(?:\/(?:[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?|\{[a-z][A-Za-z0-9]*\}))*$/.test(path);
+}
+function objectSchemaKeys(schema) {
+    return schema instanceof z.ZodObject ? Object.keys(schema.shape) : null;
+}
+function assertRequestLocations(request, operationId) {
+    for (const location of ['params', 'query', 'headers', 'body']) {
+        if (!(location in request) || request[location] === undefined)
+            throw new TypeError(`${operationId}: request.${location} must be a schema or null`);
+    }
+    for (const location of ['params', 'query', 'headers']) {
+        const schema = request[location];
+        if (schema !== null && objectSchemaKeys(schema) === null)
+            throw new TypeError(`${operationId}: request.${location} must be an object schema or null`);
+    }
+    for (const key of request.query ? objectSchemaKeys(request.query) ?? [] : []) {
+        if (!/^[a-z][A-Za-z0-9]*$/.test(key))
+            throw new TypeError(`${operationId}: query key ${key} must be a safe camelCase identifier`);
+    }
+    for (const key of request.headers ? objectSchemaKeys(request.headers) ?? [] : []) {
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(key))
+            throw new TypeError(`${operationId}: header key ${key} must be lowercase kebab-case`);
+    }
+}
+function assertPathContract(operation) {
+    const names = pathParameterNames(operation.path);
+    if (new Set(names).size !== names.length)
+        throw new TypeError(`${operation.id}: path parameters must be unique`);
+    if (names.length === 0) {
+        if (operation.request.params !== null)
+            throw new TypeError(`${operation.id}: params must be null when the path has no parameters`);
+        return;
+    }
+    if (operation.request.params === null)
+        throw new TypeError(`${operation.id}: path parameters require a params schema`);
+    const keys = objectSchemaKeys(operation.request.params);
+    if (!keys)
+        throw new TypeError(`${operation.id}: params must be an object schema`);
+    if (names.join('\0') !== keys.join('\0'))
+        throw new TypeError(`${operation.id}: params schema keys must match path parameter order`);
+}
+function assertExampleLocation(operation, example, location) {
+    const schema = operation.request[location];
+    const supplied = Object.hasOwn(example.request, location);
+    const value = supplied ? example.request[location] : undefined;
+    if (schema === null) {
+        if (value !== undefined)
+            throw new TypeError(`${operation.id}: example supplies request.${location} without a schema`);
+        return;
+    }
+    const parsed = schema.safeParse(supplied ? value : location === 'body' ? undefined : {});
+    if (!parsed.success)
+        throw new TypeError(`${operation.id}: example request.${location} does not satisfy its schema`);
+}
+function assertExamples(operation) {
+    if (operation.docs.examples.length === 0)
+        throw new TypeError(`${operation.id}: at least one executable docs example is required`);
+    for (const example of operation.docs.examples) {
+        for (const location of ['params', 'query', 'headers', 'body'])
+            assertExampleLocation(operation, example, location);
+        const response = operation.responses[example.response.status];
+        if (!response)
+            throw new TypeError(`${operation.id}: example uses undeclared response status ${example.response.status}`);
+        if (!response.producer.safeParse(example.response.body).success)
+            throw new TypeError(`${operation.id}: example response does not satisfy the producer schema`);
+    }
+}
+function assertOperation(operation) {
+    if (!/^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+$/.test(operation.id))
+        throw new TypeError(`${operation.id}: operation ID must be a stable dotted lowercase identifier`);
+    if (!isSafePathTemplate(operation.path))
+        throw new TypeError(`${operation.id}: path must be a safe literal /api/v1 template`);
+    assertRequestLocations(operation.request, operation.id);
+    assertPathContract(operation);
+    if (operation.semantics.kind === 'query') {
+        if (operation.semantics.sideEffects !== 'none' || operation.semantics.retry !== 'idempotent')
+            throw new TypeError(`${operation.id}: queries must be side-effect-free and retryable`);
+        if (operation.semantics.readConsistency === null)
+            throw new TypeError(`${operation.id}: queries must declare read consistency`);
+    }
+    else {
+        if (operation.semantics.sideEffects !== 'state' || operation.semantics.readConsistency !== null)
+            throw new TypeError(`${operation.id}: mutations require state side effects and no read consistency`);
+    }
+    if (operation.semantics.kind === 'mutation'
+        && operation.semantics.retry === 'idempotent'
+        && operation.policy.idempotency._tag !== 'required') {
+        throw new TypeError(`${operation.id}: retryable mutations require an idempotency policy`);
+    }
+    if (operation.policy.idempotency._tag === 'required') {
+        if (operation.semantics.kind !== 'mutation')
+            throw new TypeError(`${operation.id}: query operations cannot require idempotency keys`);
+        if (!Number.isSafeInteger(operation.policy.idempotency.retentionSeconds) || operation.policy.idempotency.retentionSeconds < 1)
+            throw new TypeError(`${operation.id}: idempotency retention must be a positive number of seconds`);
+    }
+    if (operation.auth.credentials.length === 0 || operation.auth.scopes.length === 0)
+        throw new TypeError(`${operation.id}: auth credentials and scopes are required`);
+    if (new Set(operation.auth.credentials).size !== operation.auth.credentials.length)
+        throw new TypeError(`${operation.id}: auth credentials must be unique`);
+    if (new Set(operation.auth.scopes).size !== operation.auth.scopes.length)
+        throw new TypeError(`${operation.id}: auth scopes must be unique`);
+    if (operation.errors.length === 0 || new Set(operation.errors).size !== operation.errors.length)
+        throw new TypeError(`${operation.id}: unique stable errors are required`);
+    if (!operation.errorResponse.producer || !operation.errorResponse.client)
+        throw new TypeError(`${operation.id}: error response schemas are required`);
+    if (Object.keys(operation.responses).length === 0)
+        throw new TypeError(`${operation.id}: at least one success response is required`);
+    for (const status of Object.keys(operation.responses).map(Number)) {
+        if (!Number.isInteger(status) || status < 200 || status >= 300)
+            throw new TypeError(`${operation.id}: response status ${status} must be successful`);
+    }
+    if (operation.semantics.kind === 'query' && operation.resources.changes.length > 0)
+        throw new TypeError(`${operation.id}: queries cannot change resources`);
+    const params = new Set(pathParameterNames(operation.path));
+    for (const reference of [...operation.resources.reads, ...operation.resources.changes]) {
+        if (reference.idFrom.startsWith('params.') && !params.has(reference.idFrom.slice(7)))
+            throw new TypeError(`${operation.id}: resource reference ${reference.idFrom} is not a path parameter`);
+    }
+    if (!operation.docs.summary || !operation.docs.description || operation.docs.tags.length === 0)
+        throw new TypeError(`${operation.id}: public documentation metadata is incomplete`);
+    if (operation.lifecycle.sunset && !operation.lifecycle.deprecated)
+        throw new TypeError(`${operation.id}: a sunset requires a deprecated version`);
+    if (operation.lifecycle.deprecated && Number.isNaN(Date.parse(operation.lifecycle.deprecated.at)))
+        throw new TypeError(`${operation.id}: deprecation must declare an RFC-compatible date`);
+    if (operation.lifecycle.sunset && Number.isNaN(Date.parse(operation.lifecycle.sunset)))
+        throw new TypeError(`${operation.id}: sunset must declare an RFC-compatible date`);
+    if (operation.lifecycle.deprecated && operation.lifecycle.sunset
+        && Date.parse(operation.lifecycle.sunset) < Date.parse(operation.lifecycle.deprecated.at)) {
+        throw new TypeError(`${operation.id}: sunset cannot precede deprecation`);
+    }
+    if (operation.policy.meter && (!Number.isInteger(operation.policy.meter.units) || operation.policy.meter.units < 1))
+        throw new TypeError(`${operation.id}: meter units must be a positive integer`);
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(operation.policy.rate.name))
+        throw new TypeError(`${operation.id}: rate policy name must be lowercase kebab-case`);
+    if (!Number.isSafeInteger(operation.policy.rate.limit) || operation.policy.rate.limit < 1)
+        throw new TypeError(`${operation.id}: rate policy limit must be a positive integer`);
+    if (!Number.isSafeInteger(operation.policy.rate.windowSeconds) || operation.policy.rate.windowSeconds < 1)
+        throw new TypeError(`${operation.id}: rate policy window must be a positive number of seconds`);
+    if (!operation.errors.includes('rate_limited'))
+        throw new TypeError(`${operation.id}: rate-limited operations must declare rate_limited`);
+    assertExamples(operation);
+}
+export function defineOperation(operation) {
+    assertOperation(operation);
+    return operation;
+}
+export function defineRegistry(registry) {
+    const ids = new Set();
+    const routes = new Set();
+    for (const [key, operation] of Object.entries(registry.operations)) {
+        assertOperation(operation);
+        if (!operation.id.startsWith(`${registry.feature}.`))
+            throw new TypeError(`${registry.feature}: ${operation.id} must use the feature namespace`);
+        if (!key)
+            throw new TypeError(`${registry.feature}: operation registry keys cannot be empty`);
+        if (ids.has(operation.id))
+            throw new TypeError(`${registry.feature}: duplicate operation ID ${operation.id}`);
+        ids.add(operation.id);
+        const route = `${operation.method} ${operation.path}`;
+        if (routes.has(route))
+            throw new TypeError(`${registry.feature}: duplicate method/path ${route}`);
+        routes.add(route);
+    }
+    return registry;
+}
+export function defineProtocol(protocol) {
+    const ids = new Set();
+    const routes = new Set();
+    for (const registry of Object.values(protocol.registries)) {
+        defineRegistry(registry);
+        for (const operation of Object.values(registry.operations)) {
+            if (ids.has(operation.id))
+                throw new TypeError(`Duplicate operation ID ${operation.id}`);
+            ids.add(operation.id);
+            const route = `${operation.method} ${operation.path}`;
+            if (routes.has(route))
+                throw new TypeError(`Duplicate public method/path ${route}`);
+            routes.add(route);
+        }
+    }
+    return protocol;
+}
+export function listOperations(protocol) {
+    const entries = [];
+    for (const registry of Object.values(protocol.registries)) {
+        for (const operation of Object.values(registry.operations))
+            entries.push({ registry, operation });
+    }
+    return entries;
+}
+export function defineResponseObject(producerShape, clientShape) {
+    return {
+        producer: z.strictObject(producerShape),
+        client: z.looseObject(clientShape ?? producerShape),
+    };
+}
+export function buildOperationPath(operation, params) {
+    const names = pathParameterNames(operation.path);
+    if (names.length === 0) {
+        if (params !== undefined && params !== null && (typeof params !== 'object' || Object.keys(params).length > 0))
+            throw new TypeError(`${operation.id}: this operation has no path parameters`);
+        return operation.path;
+    }
+    if (operation.request.params === null)
+        throw new TypeError(`${operation.id}: operation has an invalid path contract`);
+    const parsed = operation.request.params.parse(params);
+    return operation.path.replace(/\{([^{}]+)\}/g, (_match, name) => {
+        const value = parsed[name];
+        if (typeof value !== 'string' && typeof value !== 'number')
+            throw new TypeError(`${operation.id}: path parameter ${name} must serialize as a string or number`);
+        const serialized = String(value);
+        if (!serialized || serialized === '.' || serialized === '..')
+            throw new TypeError(`${operation.id}: path parameter ${name} cannot be empty or a dot segment`);
+        return encodeURIComponent(serialized);
+    });
+}
+export const publicV1ErrorDetailsSchema = z.record(z.string(), z.unknown());
+export const publicV1ErrorProducerSchema = z.strictObject({
+    code: z.enum(PUBLIC_V1_ERROR_CODES),
+    message: z.string().min(1),
+    requestId: z.string().min(1),
+    retryable: z.boolean(),
+    details: publicV1ErrorDetailsSchema,
+});
+export const publicV1ErrorClientSchema = z.looseObject({
+    code: z.enum(PUBLIC_V1_ERROR_CODES),
+    message: z.string().min(1),
+    requestId: z.string().min(1),
+    retryable: z.boolean(),
+    details: publicV1ErrorDetailsSchema,
+});
+export const publicV1ErrorEnvelope = defineResponseObject({ error: publicV1ErrorProducerSchema }, { error: publicV1ErrorClientSchema });
+export const publicV1MetaProducerSchema = z.strictObject({
+    requestId: z.string().min(1),
+    version: z.literal(PUBLIC_V1_VERSION),
+});
+export const publicV1MetaClientSchema = z.looseObject({
+    requestId: z.string().min(1),
+    version: z.literal(PUBLIC_V1_VERSION),
+});
+export function defineSuccessEnvelope(data, meta = {
+    producer: publicV1MetaProducerSchema,
+    client: publicV1MetaClientSchema,
+}) {
+    return defineResponseObject({ data: data.producer, meta: meta.producer }, { data: data.client, meta: meta.client });
+}

package/dist/v1/documents.d.ts

@@ -0,0 +1,4 @@
+import type { PublicV1ProtocolLike } from './core.js';
+export type ContractDocument = Record<string, unknown>;
+export declare function serializeContractDocument(document: ContractDocument): string;
+export declare function buildOpenApiDocument(protocol: PublicV1ProtocolLike): ContractDocument;

package/dist/v1/documents.js

@@ -0,0 +1,216 @@
+import { z } from 'zod';
+import { listOperations, PUBLIC_V1_ERROR_STATUS, PUBLIC_V1_RESPONSE_HEADERS } from './core.js';
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function orderedJson(value) {
+    if (Array.isArray(value))
+        return value.map(orderedJson);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => compareStrings(left, right))
+        .map(([key, item]) => [key, orderedJson(item)]));
+}
+export function serializeContractDocument(document) {
+    return `${JSON.stringify(orderedJson(document))}\n`;
+}
+function jsonSchema(schema, io = 'output') {
+    // Request codecs/transforms document the wire input. Zod otherwise rejects
+    // transforms before OpenAPI generation reaches their representable side.
+    const document = z.toJSONSchema(schema, { io });
+    const { $schema: _schema, ...body } = document;
+    return orderedJson(body);
+}
+function rewriteDefinitionRefs(value, references) {
+    if (Array.isArray(value))
+        return value.map(item => rewriteDefinitionRefs(item, references));
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => {
+        if (key === '$ref' && typeof item === 'string' && item.startsWith('#/$defs/')) {
+            const name = item.slice('#/$defs/'.length);
+            const reference = references[name];
+            if (!reference)
+                throw new TypeError(`JSON Schema references unknown definition ${name}`);
+            return [key, reference];
+        }
+        return [key, rewriteDefinitionRefs(item, references)];
+    }));
+}
+function registerComponentSchema(schema, name, components, io = 'output') {
+    const document = jsonSchema(schema, io);
+    const { $defs, ...body } = document;
+    if ($defs) {
+        const definitions = $defs;
+        const references = Object.fromEntries(Object.keys(definitions).map(definition => [definition, `#/components/schemas/${name}.${definition}`]));
+        for (const [definition, value] of Object.entries(definitions)) {
+            const componentName = `${name}.${definition}`;
+            if (componentName in components)
+                throw new TypeError(`Duplicate generated component schema ${componentName}`);
+            components[componentName] = rewriteDefinitionRefs(value, references);
+        }
+        components[name] = rewriteDefinitionRefs(body, references);
+    }
+    else {
+        components[name] = body;
+    }
+    return { $ref: `#/components/schemas/${name}` };
+}
+function objectParameters(schema, location, operation, components) {
+    if (schema === null)
+        return [];
+    const document = jsonSchema(schema, 'input');
+    const properties = document.properties;
+    if (!properties)
+        throw new TypeError(`OpenAPI ${location} schema must compile to object properties`);
+    const required = new Set(Array.isArray(document.required) ? document.required : []);
+    const component = `${operation.id}.${location}.request`;
+    registerComponentSchema(schema, component, components, 'input');
+    const requestLocation = { header: 'headers', path: 'params', query: 'query' };
+    const example = operation.docs.examples[0]?.request[requestLocation[location]];
+    return Object.keys(properties).map(name => ({
+        in: location,
+        name,
+        required: location === 'path' || required.has(name),
+        schema: { $ref: `#/components/schemas/${component}/properties/${name}` },
+        ...(example && Object.hasOwn(example, name) ? { example: example[name] } : {}),
+    }));
+}
+function commonResponseHeaders(operation) {
+    return {
+        [PUBLIC_V1_RESPONSE_HEADERS.requestId]: { schema: { type: 'string' } },
+        [PUBLIC_V1_RESPONSE_HEADERS.version]: { schema: { const: '1.0', type: 'string' } },
+        [PUBLIC_V1_RESPONSE_HEADERS.operation]: { schema: { const: operation.id, type: 'string' } },
+        [PUBLIC_V1_RESPONSE_HEADERS.rateLimitPolicy]: {
+            description: 'Active quota policy. This is present even when the request did not consume quota.',
+            schema: { type: 'string' },
+        },
+        [PUBLIC_V1_RESPONSE_HEADERS.rateLimit]: {
+            description: 'Remaining quota and reset metadata after a valid scoped principal consumes quota.',
+            schema: { type: 'string' },
+        },
+        [PUBLIC_V1_RESPONSE_HEADERS.retryAfter]: {
+            description: 'Delay in seconds before a retry when the response is retryable.',
+            schema: { type: 'integer', minimum: 0 },
+        },
+        ...(operation.lifecycle.deprecated
+            ? { [PUBLIC_V1_RESPONSE_HEADERS.deprecation]: { schema: { type: 'string' } } }
+            : {}),
+        ...(operation.lifecycle.sunset
+            ? { [PUBLIC_V1_RESPONSE_HEADERS.sunset]: { schema: { type: 'string', format: 'http-date' } } }
+            : {}),
+    };
+}
+function idempotencyParameters(operation) {
+    const policy = operation.policy.idempotency;
+    if (policy._tag === 'none')
+        return [];
+    return [{
+            description: `Required for safe replay. Results remain replayable for ${policy.retentionSeconds} seconds.`,
+            in: 'header',
+            name: policy.header,
+            required: true,
+            schema: { type: 'string', minLength: 1, maxLength: 255 },
+        }];
+}
+function successResponses(operation, components) {
+    return Object.fromEntries(Object.entries(operation.responses).map(([status, response]) => {
+        const component = `${operation.id}.${status}.response`;
+        const example = operation.docs.examples.find(item => item.response.status === Number(status))?.response.body;
+        return [status, {
+                description: 'Successful response.',
+                headers: commonResponseHeaders(operation),
+                content: {
+                    'application/json': {
+                        schema: registerComponentSchema(response.producer, component, components),
+                        ...(example === undefined ? {} : { example }),
+                    },
+                },
+            }];
+    }));
+}
+function errorResponses(operation, components) {
+    const component = `${operation.id}.error`;
+    const schema = registerComponentSchema(operation.errorResponse.producer, component, components);
+    const byStatus = new Map();
+    for (const code of operation.errors) {
+        const status = PUBLIC_V1_ERROR_STATUS[code];
+        byStatus.set(status, [...(byStatus.get(status) ?? []), code]);
+    }
+    return Object.fromEntries(Array.from(byStatus.entries(), ([status, codes]) => [String(status), {
+            'description': `Stable errors: ${codes.join(', ')}.`,
+            'x-nuxtseo-error-codes': codes,
+            'headers': commonResponseHeaders(operation),
+            'content': { 'application/json': { schema } },
+        }]));
+}
+function requestBody(operation, components) {
+    if (operation.request.body === null)
+        return undefined;
+    const component = `${operation.id}.body.request`;
+    const example = operation.docs.examples.find(item => Object.hasOwn(item.request, 'body'))?.request.body;
+    return {
+        required: true,
+        content: {
+            'application/json': {
+                schema: registerComponentSchema(operation.request.body, component, components, 'input'),
+                ...(example === undefined ? {} : { example }),
+            },
+        },
+    };
+}
+function operationDocument(operation, components) {
+    const parameters = [
+        ...objectParameters(operation.request.params, 'path', operation, components),
+        ...objectParameters(operation.request.query, 'query', operation, components),
+        ...objectParameters(operation.request.headers, 'header', operation, components),
+        ...idempotencyParameters(operation),
+    ];
+    const body = requestBody(operation, components);
+    return {
+        'operationId': operation.id,
+        'summary': operation.docs.summary,
+        'description': operation.docs.description,
+        'tags': operation.docs.tags,
+        'security': operation.auth.credentials.map(credential => credential === 'session'
+            ? { sessionAuth: [] }
+            : { bearerAuth: [] }),
+        ...(parameters.length === 0 ? {} : { parameters }),
+        ...(body ? { requestBody: body } : {}),
+        'responses': {
+            ...successResponses(operation, components),
+            ...errorResponses(operation, components),
+        },
+        'x-nuxtseo-auth': operation.auth,
+        'x-nuxtseo-lifecycle': operation.lifecycle,
+        'x-nuxtseo-policy': operation.policy,
+        'x-nuxtseo-resources': operation.resources,
+        'x-nuxtseo-semantics': operation.semantics,
+    };
+}
+export function buildOpenApiDocument(protocol) {
+    const components = {};
+    const paths = {};
+    for (const { operation } of listOperations(protocol)) {
+        const path = paths[operation.path] ?? {};
+        path[operation.method.toLowerCase()] = operationDocument(operation, components);
+        paths[operation.path] = path;
+    }
+    return orderedJson({
+        openapi: '3.1.0',
+        info: {
+            title: 'NuxtSEO Public API',
+            version: protocol.version,
+            description: 'Stable Team-scoped operations used by NuxtSEO clients.',
+        },
+        paths,
+        components: {
+            securitySchemes: {
+                bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'NuxtSEO API token' },
+                sessionAuth: { type: 'apiKey', in: 'cookie', name: 'nuxt-session' },
+            },
+            schemas: components,
+        },
+    });
+}