@openapi-flow/core 0.1.0 → 0.2.0

package/dist/openapi/request/parse-security.js

@@ -0,0 +1,31 @@
+import { dereferencedObject, object } from '../common/parse-spec-utils.js';
+import { UnsupportedOperationError } from '../common/unsupported-operation-error.js';
+export function parseOperationSecurity(spec, operation, operationRef) {
+    const security = operation.security === undefined ? spec.security : operation.security;
+    if (security === undefined)
+        return undefined;
+    if (!Array.isArray(security)) {
+        throw new Error(`operationRef ${operationRef}.security must be an array`);
+    }
+    if (security.length === 0)
+        return undefined;
+    if (security.length !== 1) {
+        throw new UnsupportedOperationError(operationRef, `operationRef ${operationRef}.security has unsupported alternatives`);
+    }
+    const requirement = object(security[0], `operationRef ${operationRef}.security[0]`);
+    const names = Object.keys(requirement);
+    if (names.length === 0)
+        return undefined;
+    if (names.length !== 1) {
+        throw new UnsupportedOperationError(operationRef, `operationRef ${operationRef}.security has unsupported combined schemes`);
+    }
+    const schemeName = names[0];
+    const schemes = object(object(spec.components, `operationRef ${operationRef}.components`)
+        .securitySchemes, `operationRef ${operationRef}.components.securitySchemes`);
+    const scheme = dereferencedObject(schemes[schemeName], `operationRef ${operationRef}.components.securitySchemes.${schemeName}`);
+    if (scheme.type !== 'http' ||
+        String(scheme.scheme).toLowerCase() !== 'bearer') {
+        throw new UnsupportedOperationError(operationRef, `operationRef ${operationRef}.security.${schemeName} cannot be mapped to a supported n8n credential`);
+    }
+    return { schemeName, credentialType: 'httpBearerAuth' };
+}

package/dist/openapi/request/request-operation-reference.d.ts

@@ -0,0 +1 @@
+export declare function requestOperationReference(path: string, key: string): string;

package/dist/openapi/request/request-operation-reference.js

@@ -0,0 +1,4 @@
+import { pointerSegment } from '../common/operation-reference.js';
+export function requestOperationReference(path, key) {
+    return '#/paths/' + pointerSegment(path) + '/' + key;
+}

package/dist/openapi/request/response-contract.d.ts

@@ -0,0 +1,6 @@
+import type { JsonObject } from '../../types/openapi.js';
+import type { Operation } from '../../types/request.js';
+export declare function responseFieldNames(operation: Operation): string[];
+export declare function responseFieldSchemas(operation: Operation, field: string): (JsonObject | boolean)[];
+export declare function validateResponseField(operation: Operation, field: string, value: unknown, source: string): void;
+export declare function responseFieldType(operation: Operation, field: string): string;

package/dist/openapi/request/response-contract.js

@@ -0,0 +1,32 @@
+import { checkSchemaValue } from '../common/check-schema-value.js';
+import { scalarResponseSchema } from './scalar-response-schema.js';
+export function responseFieldNames(operation) {
+    return [...new Set(Object.values(operation.responses).flatMap(Object.keys))];
+}
+export function responseFieldSchemas(operation, field) {
+    return Object.values(operation.responses).flatMap((properties) => Object.hasOwn(properties, field) ? [properties[field]] : []);
+}
+export function validateResponseField(operation, field, value, source) {
+    const schemas = responseFieldSchemas(operation, field);
+    if (schemas.length === 0)
+        throw new Error(source + ' is not in the OAS response schema');
+    for (const schema of schemas) {
+        try {
+            checkSchemaValue(value, schema, source);
+            return;
+        }
+        catch {
+            // Another declared response may define this field differently.
+        }
+    }
+    throw new Error(source + ' does not match the OAS schema');
+}
+export function responseFieldType(operation, field) {
+    const schemas = responseFieldSchemas(operation, field);
+    if (schemas.length === 0)
+        throw new Error('prior response field ' + field + ' is not in the OAS');
+    const types = new Set(schemas.map((schema) => scalarResponseSchema(schema, 'operationRef ' + operation.operationRef + ' response field ' + field, operation.operationRef).type));
+    if (types.size !== 1)
+        throw new Error('prior response field ' + field + ' has ambiguous OAS types');
+    return [...types][0];
+}

package/dist/openapi/request/scalar-response-schema.d.ts

@@ -0,0 +1,2 @@
+import type { ScalarSchema } from '../../types/openapi.js';
+export declare function scalarResponseSchema(value: unknown, source: string, operationRef: string): ScalarSchema;

package/dist/openapi/request/scalar-response-schema.js

@@ -0,0 +1,20 @@
+import { dereferencedObject } from '../common/parse-spec-utils.js';
+import { UnsupportedOperationError } from '../common/unsupported-operation-error.js';
+export function scalarResponseSchema(value, source, operationRef) {
+    const schema = dereferencedObject(value, source);
+    if (!['string', 'integer', 'number', 'boolean'].includes(String(schema.type))) {
+        throw new UnsupportedOperationError(operationRef, `${source} must be a primitive schema`);
+    }
+    if (schema.enum !== undefined &&
+        (!Array.isArray(schema.enum) ||
+            schema.enum.length === 0 ||
+            schema.enum.some((entry) => typeof entry !== 'string' &&
+                typeof entry !== 'number' &&
+                typeof entry !== 'boolean'))) {
+        throw new UnsupportedOperationError(operationRef, `${source}.enum must contain primitive values`);
+    }
+    return {
+        type: schema.type,
+        enum: schema.enum,
+    };
+}

package/dist/openapi/request/serialize-form-body.d.ts

@@ -0,0 +1,3 @@
+import type { JsonObject } from '../../types/openapi.js';
+import type { OperationBodyMedia } from '../../types/request.js';
+export declare function serializeFormBody(operationRef: string, media: OperationBodyMedia, value: JsonObject): string;

package/dist/openapi/request/serialize-form-body.js

@@ -0,0 +1,89 @@
+import { serializeQueryParameter } from './serialize-parameter.js';
+import { UnsupportedOperationError } from '../common/unsupported-operation-error.js';
+import { dereferencedObject } from '../common/parse-spec-utils.js';
+import { isObject } from '../../utils/is-object.js';
+import { encodeFormField } from './encode-form-field.js';
+function defaultFieldMediaType(schema) {
+    const type = schema.type === 'array' && isObject(schema.items)
+        ? schema.items.type
+        : schema.type;
+    if (type === 'object' || type === 'array')
+        return 'application/json';
+    if (['string', 'number', 'integer', 'boolean'].includes(String(type)))
+        return 'text/plain';
+    return undefined;
+}
+function encodedField(name, field, schema, contentType, operationRef) {
+    if (contentType !== 'application/json' && contentType !== 'text/plain')
+        throw new UnsupportedOperationError(operationRef, `operationRef ${operationRef}.requestBody field ${name} contentType ${contentType} has no form mapping`);
+    const values = Array.isArray(field) ? field : [field];
+    if (values.length === 0)
+        return [];
+    const form = [];
+    for (const value of values) {
+        if (contentType === 'text/plain' && typeof value === 'object')
+            throw new UnsupportedOperationError(operationRef, `operationRef ${operationRef}.requestBody field ${name} cannot use text/plain for a complex value`);
+        if (contentType === 'application/json') {
+            form.push(encodeFormField(name) + '=' + encodeFormField(JSON.stringify(value)));
+        }
+        else {
+            form.push(encodeFormField(name) + '=' + encodeFormField(String(value)));
+        }
+    }
+    if (schema.contentEncoding !== undefined)
+        throw new UnsupportedOperationError(operationRef, `operationRef ${operationRef}.requestBody field ${name} contentEncoding requires explicit binary serialization`);
+    return form;
+}
+function formFieldSchema(operationRef, media, name) {
+    const source = `operationRef ${operationRef}.requestBody.schema.properties.${name}`;
+    const declared = media.properties[name];
+    if (declared !== undefined) {
+        if (typeof declared === 'boolean')
+            throw new UnsupportedOperationError(operationRef, `${source} does not define a form encoding type`);
+        return dereferencedObject(declared, source);
+    }
+    if (isObject(media.schema) && media.schema.additionalProperties !== undefined)
+        if (typeof media.schema.additionalProperties !== 'boolean')
+            return dereferencedObject(media.schema.additionalProperties, `operationRef ${operationRef}.requestBody.schema.additionalProperties`);
+    throw new UnsupportedOperationError(operationRef, `operationRef ${operationRef}.requestBody field ${name} has no schema to determine form encoding`);
+}
+export function serializeFormBody(operationRef, media, value) {
+    const parts = [];
+    for (const [name, field] of Object.entries(value)) {
+        const schema = formFieldSchema(operationRef, media, name);
+        const rawEncoding = media.encoding?.[name];
+        const encoding = rawEncoding === undefined
+            ? undefined
+            : dereferencedObject(rawEncoding, `operationRef ${operationRef}.requestBody.encoding.${name}`);
+        if (encoding?.encoding !== undefined ||
+            encoding?.prefixEncoding !== undefined ||
+            encoding?.itemEncoding !== undefined)
+            throw new UnsupportedOperationError(operationRef, `operationRef ${operationRef}.requestBody field ${name} needs nested encoding`);
+        const usesStyle = encoding?.style !== undefined ||
+            encoding?.explode !== undefined ||
+            encoding?.allowReserved !== undefined;
+        if (usesStyle) {
+            const style = typeof encoding?.style === 'string' ? encoding.style : 'form';
+            const parameter = {
+                name,
+                in: 'query',
+                required: false,
+                schema,
+                style,
+                explode: typeof encoding?.explode === 'boolean'
+                    ? encoding.explode
+                    : style === 'form',
+                allowReserved: encoding?.allowReserved === true,
+            };
+            parts.push(...serializeQueryParameter(parameter, operationRef, field));
+            continue;
+        }
+        const contentType = typeof encoding?.contentType === 'string'
+            ? encoding.contentType
+            : defaultFieldMediaType(schema);
+        if (contentType === undefined)
+            throw new UnsupportedOperationError(operationRef, `operationRef ${operationRef}.requestBody field ${name} has no form content mapping`);
+        parts.push(...encodedField(name, field, schema, contentType, operationRef));
+    }
+    return parts.join('&');
+}

package/dist/openapi/request/serialize-parameter.d.ts

@@ -0,0 +1,5 @@
+import type { OperationParameter } from '../../types/request.js';
+export declare function serializePathParameter(parameter: OperationParameter, operationRef: string, value: unknown): string;
+export declare function serializeQueryParameter(parameter: OperationParameter, operationRef: string, value: unknown): string[];
+export declare function serializeHeaderParameter(parameter: OperationParameter, operationRef: string, value: unknown): string;
+export declare function serializeCookieParameter(parameter: OperationParameter, operationRef: string, value: unknown): string[];

package/dist/openapi/request/serialize-parameter.js

@@ -0,0 +1,145 @@
+import { isObject } from '../../utils/is-object.js';
+import { UnsupportedOperationError } from '../common/unsupported-operation-error.js';
+function unsupported(parameter, operationRef, reason) {
+    throw new UnsupportedOperationError(operationRef, `operationRef ${operationRef} parameter ${parameter.in}.${parameter.name} ${reason}`);
+}
+function flatValue(parameter, operationRef, value) {
+    if (typeof value === 'string' ||
+        typeof value === 'boolean' ||
+        (typeof value === 'number' && Number.isFinite(value)))
+        return value;
+    return unsupported(parameter, operationRef, 'requires a scalar value');
+}
+function encoded(value, allowReserved) {
+    const escaped = encodeURIComponent(String(value)).replace(/[!'()*]/g, (character) => '%' + character.charCodeAt(0).toString(16).toUpperCase());
+    if (!allowReserved)
+        return escaped;
+    return escaped.replace(/%(3A|2F|3F|23|5B|5D|40|21|24|26|27|28|29|2A|2B|2C|3B|3D)/gi, (match) => String.fromCharCode(Number.parseInt(match.slice(1), 16)));
+}
+function entries(parameter, operationRef, value, encode) {
+    if (Array.isArray(value))
+        return value.map((item) => encode(flatValue(parameter, operationRef, item)));
+    if (isObject(value))
+        return Object.entries(value).flatMap(([key, item]) => [
+            encode(key),
+            encode(flatValue(parameter, operationRef, item)),
+        ]);
+    return [encode(flatValue(parameter, operationRef, value))];
+}
+function contentValue(parameter, operationRef, value) {
+    if (parameter.contentMediaType !== 'application/json')
+        return unsupported(parameter, operationRef, 'has no content mapping');
+    const result = JSON.stringify(value);
+    if (result === undefined)
+        return unsupported(parameter, operationRef, 'cannot be JSON serialized');
+    return result;
+}
+export function serializePathParameter(parameter, operationRef, value) {
+    if (parameter.contentMediaType) {
+        return encoded(contentValue(parameter, operationRef, value), false);
+    }
+    const encode = (scalar) => encoded(scalar, parameter.allowReserved);
+    const parts = entries(parameter, operationRef, value, encode);
+    const object = isObject(value);
+    if (parameter.style === 'simple') {
+        if (!object || !parameter.explode)
+            return parts.join(',');
+        return parts
+            .flatMap((item, index) => index % 2 === 0 ? [item + '=' + parts[index + 1]] : [])
+            .join(',');
+    }
+    if (parameter.style === 'label') {
+        if (!object || !parameter.explode)
+            return '.' + parts.join(parameter.explode ? '.' : ',');
+        return ('.' +
+            parts
+                .flatMap((item, index) => index % 2 === 0 ? [item + '=' + parts[index + 1]] : [])
+                .join('.'));
+    }
+    if (parameter.style === 'matrix') {
+        const name = encoded(parameter.name, false);
+        if (!parameter.explode)
+            return ';' + name + '=' + parts.join(',');
+        if (object)
+            return parts
+                .flatMap((item, index) => index % 2 === 0 ? [';' + item + '=' + parts[index + 1]] : [])
+                .join('');
+        return parts.map((item) => ';' + name + '=' + item).join('');
+    }
+    return unsupported(parameter, operationRef, `style ${parameter.style} is not a path style`);
+}
+export function serializeQueryParameter(parameter, operationRef, value) {
+    const name = encoded(parameter.name, false);
+    if (parameter.contentMediaType)
+        return [
+            name + '=' + encoded(contentValue(parameter, operationRef, value), false),
+        ];
+    const encode = (scalar) => encoded(scalar, parameter.allowReserved);
+    const parts = entries(parameter, operationRef, value, encode);
+    const object = isObject(value);
+    if (parameter.style === 'deepObject') {
+        if (!object)
+            return unsupported(parameter, operationRef, 'deepObject requires an object');
+        return parts.flatMap((item, index) => index % 2 === 0 ? [name + '%5B' + item + '%5D=' + parts[index + 1]] : []);
+    }
+    if (parameter.style === 'form') {
+        if (!parameter.explode)
+            return [name + '=' + parts.join(',')];
+        if (object)
+            return parts.flatMap((item, index) => index % 2 === 0 ? [item + '=' + parts[index + 1]] : []);
+        return parts.map((item) => name + '=' + item);
+    }
+    if ((parameter.style === 'spaceDelimited' ||
+        parameter.style === 'pipeDelimited') &&
+        !parameter.explode &&
+        (object || Array.isArray(value))) {
+        return [
+            name +
+                '=' +
+                parts.join(parameter.style === 'spaceDelimited' ? '%20' : '%7C'),
+        ];
+    }
+    return unsupported(parameter, operationRef, `style ${parameter.style} is not mapped for query`);
+}
+export function serializeHeaderParameter(parameter, operationRef, value) {
+    if (parameter.contentMediaType)
+        return contentValue(parameter, operationRef, value);
+    if (parameter.style !== 'simple')
+        return unsupported(parameter, operationRef, `style ${parameter.style} is not a header style`);
+    const parts = entries(parameter, operationRef, value, String);
+    const result = isObject(value) && parameter.explode
+        ? parts
+            .flatMap((item, index) => index % 2 === 0 ? [item + '=' + parts[index + 1]] : [])
+            .join(',')
+        : parts.join(',');
+    if (/[\r\n]/.test(result))
+        throw new Error(`plan.inputs.header.${parameter.name} must not contain a newline`);
+    return result;
+}
+export function serializeCookieParameter(parameter, operationRef, value) {
+    if (parameter.contentMediaType)
+        return unsupported(parameter, operationRef, 'cookie content needs a declared escaping strategy');
+    if (parameter.style !== 'form' && parameter.style !== 'cookie')
+        return unsupported(parameter, operationRef, `style ${parameter.style} is not a cookie style`);
+    const encode = parameter.style === 'cookie'
+        ? (scalar) => String(scalar)
+        : (scalar) => encoded(scalar, parameter.allowReserved);
+    const parts = entries(parameter, operationRef, value, encode);
+    const name = encode(parameter.name);
+    if (!parameter.explode && (isObject(value) || Array.isArray(value)))
+        return unsupported(parameter, operationRef, 'explode:false produces invalid Cookie syntax');
+    const result = isObject(value)
+        ? parts.flatMap((item, index) => index % 2 === 0 ? [item + '=' + parts[index + 1]] : [])
+        : parts.map((item) => name + '=' + item);
+    if (result.some((part) => [...part].some((character) => {
+        const code = character.charCodeAt(0);
+        return (code <= 32 ||
+            code === 34 ||
+            code === 44 ||
+            code === 59 ||
+            code === 92 ||
+            code === 127);
+    })))
+        return unsupported(parameter, operationRef, 'value is not valid Cookie syntax');
+    return result;
+}

package/dist/openapi/resolve-api-operations.d.ts

@@ -0,0 +1,3 @@
+import type { ApiCatalog, ApiOperationKey } from '../types/api-catalog.js';
+import type { ApiOperationContract } from '../types/api-operation.js';
+export declare function resolveApiOperations(catalog: ApiCatalog, keys: ApiOperationKey[]): Promise<ApiOperationContract[]>;

package/dist/openapi/resolve-api-operations.js

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto';
+import { object } from './common/parse-spec-utils.js';
+import { validateAndResolveOpenApiDocument } from './common/validate-spec.js';
+import { selectedOperationSource } from './request/parse-request-operations.js';
+export async function resolveApiOperations(catalog, keys) {
+    if (!Array.isArray(keys))
+        throw new Error('operation keys must be an array');
+    const documents = new Map();
+    const contracts = [];
+    for (const key of keys) {
+        if (!key ||
+            typeof key.documentId !== 'string' ||
+            !key.documentId.trim() ||
+            typeof key.snapshotId !== 'string' ||
+            !key.snapshotId ||
+            typeof key.operationRef !== 'string' ||
+            !key.operationRef)
+            throw new Error('operation keys require documentId, snapshotId and operationRef');
+        const source = catalog.documents.find((item) => item.id === key.documentId);
+        if (!source)
+            throw new Error(`operation.documentId ${key.documentId} is not in catalog`);
+        if (source.snapshotId !== key.snapshotId)
+            throw new Error(`operation.snapshotId does not match sources[${source.id}]`);
+        if (createHash('sha256').update(JSON.stringify(source.spec)).digest('hex') !==
+            source.snapshotId)
+            throw new Error(`sources[${source.id}].spec changed after catalog creation`);
+        if (!catalog.operations.some((item) => item.key.documentId === key.documentId &&
+            item.operationRef === key.operationRef))
+            throw new Error(`sources[${source.id}] has no operationRef ${key.operationRef}`);
+        let document = documents.get(source.id);
+        if (!document) {
+            document = await validateAndResolveOpenApiDocument(source.spec);
+            documents.set(source.id, document);
+        }
+        const { candidate, pathItem, entry } = selectedOperationSource(document, key.operationRef);
+        const operation = object(entry.value, `sources[${source.id}].${key.operationRef}`);
+        const parameters = new Map();
+        for (const level of [pathItem, operation]) {
+            if (level.parameters === undefined)
+                continue;
+            if (!Array.isArray(level.parameters))
+                throw new Error(`sources[${source.id}].${key.operationRef}.parameters must be an array`);
+            for (const raw of level.parameters) {
+                const parameter = object(raw, `${key.operationRef}.parameters`);
+                parameters.set(JSON.stringify([parameter.in, parameter.name]), parameter);
+            }
+        }
+        const security = operation.security === undefined
+            ? document.spec.security
+            : operation.security;
+        const servers = operation.servers === undefined
+            ? pathItem.servers === undefined
+                ? document.spec.servers
+                : pathItem.servers
+            : operation.servers;
+        const components = document.spec.components === undefined
+            ? undefined
+            : object(document.spec.components, 'spec.components');
+        if (typeof document.spec.openapi !== 'string')
+            throw new Error(`sources[${source.id}].spec.openapi is missing`);
+        contracts.push({
+            key: { ...key },
+            openapiVersion: document.spec.openapi,
+            source: 'paths',
+            method: candidate.method,
+            path: candidate.path,
+            operation: structuredClone(operation),
+            pathItem: structuredClone(pathItem),
+            effective: {
+                parameters: [...parameters.values()],
+                security: security === undefined
+                    ? []
+                    : structuredClone(security),
+                securitySchemes: components?.securitySchemes === undefined
+                    ? {}
+                    : object(components.securitySchemes, 'spec.components.securitySchemes'),
+                ...(servers === undefined
+                    ? {}
+                    : { servers: structuredClone(servers) }),
+            },
+        });
+    }
+    return contracts;
+}

package/dist/openapi/response/api-response-validation-value.d.ts

@@ -0,0 +1,3 @@
+import type { ApiResponseEnvelope, ApiResponseValidationValue } from '../../types/api-response.js';
+/** Project transport metadata for validation without rewriting response data. */
+export declare function apiResponseValidationValue(response: ApiResponseEnvelope): ApiResponseValidationValue;

package/dist/openapi/response/api-response-validation-value.js

@@ -0,0 +1,21 @@
+/** Project transport metadata for validation without rewriting response data. */
+export function apiResponseValidationValue(response) {
+    if (!response || !Number.isInteger(response.statusCode))
+        throw new Error('API response.statusCode is required');
+    if (!response.headers ||
+        typeof response.headers !== 'object' ||
+        Array.isArray(response.headers))
+        throw new Error('API response.headers is required');
+    const headers = Object.entries(response.headers).filter(([name]) => name.toLowerCase() === 'content-type');
+    if (headers.length > 1)
+        throw new Error('API response.headers has ambiguous Content-Type');
+    const value = { statusCode: response.statusCode };
+    if (headers.length) {
+        if (typeof headers[0][1] !== 'string')
+            throw new Error('API response Content-Type must be a string');
+        value.mediaType = headers[0][1].split(';')[0].trim().toLowerCase();
+    }
+    if (Object.hasOwn(response, 'body'))
+        value.body = response.body;
+    return value;
+}

package/dist/openapi/response/create-api-response-schema.d.ts

@@ -0,0 +1,4 @@
+import type { ApiResponseValidationInput } from '../../types/api-response.js';
+import type { JsonObject } from '../../types/openapi.js';
+/** Validate the observed response, not an LLM-planned expected status. */
+export declare function createApiResponseSchema({ operation, }: ApiResponseValidationInput): JsonObject;

package/dist/openapi/response/create-api-response-schema.js

@@ -0,0 +1,114 @@
+import { isObject } from '../../utils/is-object.js';
+import { createOasValueValidator } from '../common/create-oas-value-validator.js';
+function statusSchema(key, keys) {
+    if (/^[1-5][0-9]{2}$/.test(key))
+        return { const: Number(key) };
+    if (/^[1-5]XX$/.test(key))
+        return {
+            minimum: Number(key[0]) * 100,
+            maximum: Number(key[0]) * 100 + 99,
+            ...(keys.some((item) => /^[1-5][0-9]{2}$/.test(item))
+                ? {
+                    not: {
+                        enum: keys
+                            .filter((item) => /^[1-5][0-9]{2}$/.test(item))
+                            .map(Number),
+                    },
+                }
+                : {}),
+        };
+    if (key === 'default')
+        return keys.some((item) => item !== 'default')
+            ? {
+                not: {
+                    anyOf: keys
+                        .filter((item) => item !== 'default')
+                        .map((item) => statusSchema(item, keys)),
+                },
+            }
+            : {};
+    throw new Error(`responses.${key} is not an OAS response status`);
+}
+function mediaPattern(media) {
+    return ('^' +
+        media
+            .toLowerCase()
+            .split('*')
+            .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+            .join('[^/;]+') +
+        '$');
+}
+/** Validate the observed response, not an LLM-planned expected status. */
+export function createApiResponseSchema({ operation, }) {
+    const responses = operation.operation.responses;
+    if (!isObject(responses))
+        throw new Error(`${operation.key.operationRef}.responses is required`);
+    const keys = Object.keys(responses).filter((key) => !key.startsWith('x-'));
+    const dialect = operation.openapiVersion.startsWith('3.0.')
+        ? 'openapi-3.0'
+        : 'draft-2020-12';
+    const branches = keys.flatMap((key) => {
+        const response = responses[key];
+        if (!isObject(response))
+            throw new Error(`${operation.key.operationRef}.responses.${key} must be resolved`);
+        if ('$ref' in response)
+            throw new Error(`${operation.key.operationRef}.responses.${key} must be resolved`);
+        const status = statusSchema(key, keys);
+        const content = response.content;
+        if (!isObject(content) || !Object.keys(content).length)
+            return [{ properties: { statusCode: status } }];
+        const mediaTypes = Object.keys(content);
+        return mediaTypes.map((mediaType) => {
+            const media = content[mediaType];
+            if (!isObject(media))
+                throw new Error(`${operation.key.operationRef}.responses.${key}.content.${mediaType} must be resolved`);
+            if ('$ref' in media)
+                throw new Error(`${operation.key.operationRef}.responses.${key}.content.${mediaType} must be resolved`);
+            const schema = media.schema;
+            if (schema !== undefined &&
+                typeof schema !== 'boolean' &&
+                !isObject(schema))
+                throw new Error(`${operation.key.operationRef}.responses.${key}.content.${mediaType}.schema must be an OAS schema`);
+            const body = schema === undefined
+                ? true
+                : createOasValueValidator(schema, dialect, `${operation.key.documentId}${operation.key.operationRef}/responses/${key}/${mediaType}`).schema;
+            const moreSpecific = mediaTypes.filter((other) => other !== mediaType &&
+                (mediaType === '*/*'
+                    ? other !== '*/*'
+                    : mediaType.endsWith('/*') &&
+                        !other.includes('*') &&
+                        other.split('/')[0].toLowerCase() ===
+                            mediaType.split('/')[0].toLowerCase()));
+            return {
+                properties: {
+                    statusCode: status,
+                    mediaType: {
+                        pattern: mediaPattern(mediaType),
+                        ...(moreSpecific.length
+                            ? {
+                                not: {
+                                    anyOf: moreSpecific.map((other) => ({
+                                        pattern: mediaPattern(other),
+                                    })),
+                                },
+                            }
+                            : {}),
+                    },
+                    body,
+                },
+                required: ['mediaType'],
+            };
+        });
+    });
+    return {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        properties: {
+            statusCode: { type: 'integer', minimum: 100, maximum: 599 },
+            mediaType: { type: 'string' },
+            body: true,
+        },
+        required: ['statusCode'],
+        ...(branches.length ? { anyOf: branches } : { not: {} }),
+    };
+}

package/dist/openapi/response/create-response-array-item-schema.d.ts

@@ -0,0 +1,4 @@
+import type { ApiOperationContract } from '../../types/api-operation.js';
+import type { BindingSchema } from '../../types/api-bindings.js';
+/** Item candidates come from OAS; the original full response is validated at runtime. */
+export declare function createResponseArrayItemSchema(operation: ApiOperationContract, pointer: string): BindingSchema;

package/dist/openapi/response/create-response-array-item-schema.js

@@ -0,0 +1,12 @@
+import { responseBindingSchemas } from '../../bindings/response-binding-schema.js';
+import { projectArrayItemSchema } from '../../bindings/project-array-item-schema.js';
+/** Item candidates come from OAS; the original full response is validated at runtime. */
+export function createResponseArrayItemSchema(operation, pointer) {
+    const items = responseBindingSchemas(operation, pointer).flatMap((schema) => {
+        const projection = projectArrayItemSchema(schema);
+        return projection.allowsArray ? [projection.schema] : [];
+    });
+    if (!items.length)
+        throw new Error(`${operation.key.operationRef}${pointer} has no declared response array`);
+    return { anyOf: items };
+}

package/dist/openapi/response/create-response-value-schema.d.ts

@@ -0,0 +1,4 @@
+import type { ApiOperationContract } from '../../types/api-operation.js';
+import type { BindingSchema } from '../../types/api-bindings.js';
+/** Candidate schemas for a pointer; validate the selected full response at runtime. */
+export declare function createResponseValueSchema(operation: ApiOperationContract, pointer: string): BindingSchema;

package/dist/openapi/response/create-response-value-schema.js

@@ -0,0 +1,8 @@
+import { responseBindingSchemas } from '../../bindings/response-binding-schema.js';
+/** Candidate schemas for a pointer; validate the selected full response at runtime. */
+export function createResponseValueSchema(operation, pointer) {
+    const schemas = responseBindingSchemas(operation, pointer);
+    if (!schemas.length)
+        throw new Error(`${operation.key.operationRef}${pointer} has no declared response value`);
+    return { anyOf: schemas };
+}

package/dist/openapi/response/list-api-response-pointers.d.ts

@@ -0,0 +1,4 @@
+import type { ApiOperationContract } from '../../types/api-operation.js';
+import type { ApiResponsePointerCatalog } from '../../types/api-response-pointers.js';
+/** Describe finite schema declarations, not guaranteed runtime fields or a whitelist. */
+export declare function listApiResponsePointers(operation: ApiOperationContract): ApiResponsePointerCatalog[];