@wirebench/engine 2.1.1

package/dist/rest/openapi/map.js

@@ -0,0 +1,477 @@
+/**
+ * Turning a parsed OpenAPI document into an API, its folders and its requests.
+ *
+ * Kept apart from `import.ts` because this half is pure: given a document it always produces the
+ * same tree, with no fetching, no clock and no file system. That is what makes an import reviewable
+ * — a golden test can state the whole tree — and it is the only way the mapping rules stay legible.
+ *
+ * The mapping is deliberately conservative. An imported request is a *starting point a user edits*,
+ * so where the document is ambiguous the import picks the reading that leaves the least hidden: a
+ * required query parameter is enabled and an optional one is present but switched off, a header
+ * parameter arrives switched off, and anything the mapping cannot represent is counted and named in
+ * the summary rather than dropped in silence.
+ */
+import { generateId } from '../../project/model.js';
+import { slugify, uniqueSlug } from '../../project/paths.js';
+import { createApi, createFolder, createRestRequest, entry, RAW_LANGUAGE_CONTENT_TYPES } from '../model.js';
+import { HTTP_METHODS, serverUrl } from './model.js';
+import { sampleFromSchema, sampleXml } from './sample.js';
+/** Header parameters OpenAPI itself says to ignore, because the message decides them. */
+const RESERVED_HEADERS = new Set(['accept', 'content-type', 'authorization']);
+/** The media types a *Binary* body is the honest reading of. */
+function isBinaryMedia(type, schema) {
+    if (schema?.format === 'binary') {
+        return true;
+    }
+    return (type === 'application/octet-stream' ||
+        type === 'application/pdf' ||
+        type === 'application/zip' ||
+        type.startsWith('image/') ||
+        type.startsWith('audio/') ||
+        type.startsWith('video/'));
+}
+const isJson = (type) => type === 'application/json' || /^application\/[\w.+-]+\+json$/.test(type);
+const isXml = (type) => type === 'application/xml' || type === 'text/xml' || /^application\/[\w.+-]+\+xml$/.test(type);
+const isForm = (type) => type === 'application/x-www-form-urlencoded';
+const isMultipart = (type) => type === 'multipart/form-data';
+/** JSON > XML > form > multipart > anything else, as §3.6 orders them. */
+const BODY_PREFERENCE = [isJson, isXml, isForm, isMultipart, () => true];
+/** A value as a table cell or a header: a string stays itself, anything else is written as JSON. */
+function cellText(value) {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+/** The first of a parameter's or media type's named `examples`, in document order. */
+function firstNamedExample(examples) {
+    for (const example of Object.values(examples ?? {})) {
+        if (example.value !== undefined) {
+            return example.value;
+        }
+    }
+    return undefined;
+}
+/** A parameter's value: its `example`, else its schema's, else empty (§3.6). */
+function parameterValue(parameter, options) {
+    const stated = parameter.example ?? firstNamedExample(parameter.examples);
+    if (stated !== undefined) {
+        return cellText(stated);
+    }
+    if (parameter.schema === undefined) {
+        return '';
+    }
+    const sampled = sampleFromSchema(parameter.schema, {
+        ...(options.sampleValues !== undefined ? { sampleValues: options.sampleValues } : {}),
+    });
+    // A composite parameter value has a `style` this client does not serialise; an empty cell asks
+    // the user for the one they want rather than inventing a JSON blob on the wire.
+    return typeof sampled === 'object' && sampled !== null ? '' : cellText(sampled);
+}
+/** One row per parameter in `location`, in document order. */
+function parameterRows(operation, location, options, skipped) {
+    const rows = [];
+    for (const parameter of operation.parameters) {
+        if (parameter.in !== location) {
+            continue;
+        }
+        if (location === 'header' && RESERVED_HEADERS.has(parameter.name.toLowerCase())) {
+            skipped.push({
+                kind: 'parameter',
+                where: `${operation.method.toUpperCase()} ${operation.path}`,
+                reason: `The "${parameter.name}" header is decided by the request itself`,
+            });
+            continue;
+        }
+        rows.push(entry(parameter.name, parameterValue(parameter, options), {
+            // A path parameter is always part of the URL; a query one only when the document requires
+            // it; a header one never, so an import never silently changes what goes on the wire.
+            enabled: location === 'path' || (location === 'query' && parameter.required === true),
+            ...(parameter.description !== undefined ? { description: parameter.description } : {}),
+        }));
+    }
+    return rows;
+}
+/** Every cookie parameter, counted: this client has no cookie-parameter table. */
+function noteCookieParameters(operation, skipped) {
+    for (const parameter of operation.parameters) {
+        if (parameter.in === 'cookie') {
+            skipped.push({
+                kind: 'parameter',
+                where: `${operation.method.toUpperCase()} ${operation.path}`,
+                reason: `Cookie parameter "${parameter.name}" is not imported`,
+            });
+        }
+    }
+}
+/** The media type an operation's body is built from, under {@link BODY_PREFERENCE}. */
+function preferredMedia(content) {
+    const types = Object.keys(content);
+    for (const matches of BODY_PREFERENCE) {
+        const type = types.find((candidate) => matches(candidate));
+        const media = type === undefined ? undefined : content[type];
+        if (type !== undefined && media !== undefined) {
+            return { type, media };
+        }
+    }
+    return undefined;
+}
+/** The text a raw body starts with: the media type's example, else the first of its examples, else a sample. */
+function rawText(media, language, options) {
+    const stated = media.example ?? firstNamedExample(media.examples);
+    if (stated !== undefined) {
+        if (typeof stated === 'string') {
+            return stated;
+        }
+        return JSON.stringify(stated, null, 2);
+    }
+    if (media.schema === undefined) {
+        return '';
+    }
+    const sampleOptions = {
+        ...(options.includeOptional !== undefined ? { includeOptional: options.includeOptional } : {}),
+        ...(options.sampleValues !== undefined ? { sampleValues: options.sampleValues } : {}),
+    };
+    if (language === 'xml') {
+        return sampleXml(media.schema, sampleOptions);
+    }
+    const sample = sampleFromSchema(media.schema, sampleOptions);
+    return language === 'json' ? JSON.stringify(sample, null, 2) : cellText(sample);
+}
+/** One row per property of a form schema, required ones enabled. */
+function formFields(schema, options) {
+    const required = new Set(schema?.required ?? []);
+    return Object.entries(schema?.properties ?? {}).map(([name, property]) => entry(name, cellText(sampleFromSchema(property, { ...options, maxDepth: 1 })), {
+        enabled: required.has(name),
+        ...(property.description !== undefined ? { description: property.description } : {}),
+    }));
+}
+/** One part per property of a multipart schema; a `format: binary` property becomes a file part. */
+function multipartParts(schema, options) {
+    const required = new Set(schema?.required ?? []);
+    return Object.entries(schema?.properties ?? {}).map(([name, property]) => {
+        const enabled = required.has(name);
+        if (property.format === 'binary') {
+            // No file is chosen yet, exactly as a hand-added file part starts out.
+            return { kind: 'file', name, source: { kind: 'path', path: '' }, enabled };
+        }
+        return { kind: 'text', name, value: cellText(sampleFromSchema(property, { ...options, maxDepth: 1 })), enabled };
+    });
+}
+/** The body an operation's `requestBody` maps to, and the header its media type may need. */
+function bodyOf(operation, options, skipped) {
+    const content = operation.requestBody?.content;
+    if (content === undefined) {
+        return { kind: 'none' };
+    }
+    const chosen = preferredMedia(content);
+    if (chosen === undefined) {
+        return { kind: 'none' };
+    }
+    const { type, media } = chosen;
+    for (const other of Object.keys(content)) {
+        if (other !== type) {
+            skipped.push({
+                kind: 'media-type',
+                where: `${operation.method.toUpperCase()} ${operation.path}`,
+                reason: `Offers "${other}" as well; imported as "${type}"`,
+            });
+        }
+    }
+    if (isBinaryMedia(type, media.schema)) {
+        return { kind: 'binary', source: { kind: 'path', path: '' }, contentType: type };
+    }
+    if (isForm(type)) {
+        return { kind: 'form', fields: formFields(media.schema, options) };
+    }
+    if (isMultipart(type)) {
+        return { kind: 'multipart', parts: multipartParts(media.schema, options) };
+    }
+    const language = isJson(type) ? 'json' : isXml(type) ? 'xml' : 'text';
+    return {
+        kind: 'raw',
+        language,
+        // A vendor media type (`application/vnd.api+json`) edits as JSON but must travel as itself.
+        ...(RAW_LANGUAGE_CONTENT_TYPES[language] === type ? {} : { contentType: type }),
+        text: rawText(media, language, options),
+    };
+}
+/**
+ * The credentials one security scheme maps to, or the reason none does.
+ *
+ * Separate from {@link authFromScheme} because the summary lists *every* scheme the document
+ * declares as a candidate the user may pick, and asking "what would this one become?" must not
+ * itself record that something was skipped — only a scheme the import actually needed does that.
+ */
+export function mapScheme(scheme) {
+    switch (scheme.type) {
+        case 'http':
+            if (scheme.scheme === 'basic') {
+                // Secrets are never invented: the fields are the user's to fill in (ADR-0004).
+                return { auth: { type: 'basic' } };
+            }
+            if (scheme.scheme === 'bearer') {
+                return { auth: { type: 'bearer' } };
+            }
+            return { reason: `HTTP scheme "${scheme.scheme ?? 'unnamed'}" is not supported` };
+        case 'apiKey':
+            if (scheme.in === 'header' || scheme.in === 'query') {
+                return { auth: { type: 'api-key', name: scheme.keyName ?? '', in: scheme.in } };
+            }
+            return { reason: 'An API key in a cookie is not supported' };
+        case 'oauth2': {
+            const clientCredentials = scheme.flows?.clientCredentials;
+            const authorizationCode = scheme.flows?.authorizationCode;
+            const flow = clientCredentials ?? authorizationCode;
+            if (flow === undefined) {
+                return { reason: 'Only the client-credentials and authorization-code flows are supported' };
+            }
+            return {
+                auth: {
+                    type: 'oauth2',
+                    grant: clientCredentials !== undefined ? 'client-credentials' : 'authorization-code',
+                    tokenUrl: flow.tokenUrl ?? '',
+                    ...(flow.authorizationUrl !== undefined ? { authorizationUrl: flow.authorizationUrl } : {}),
+                    clientId: '',
+                    scopes: Object.keys(flow.scopes ?? {}),
+                    clientAuth: 'basic',
+                    // PKCE is what makes an authorization-code flow safe in a public client; a
+                    // client-credentials flow has no authorization request to protect.
+                    pkce: clientCredentials === undefined,
+                },
+            };
+        }
+        default:
+            return { reason: `Security scheme type "${scheme.type}" is not supported` };
+    }
+}
+/** {@link mapScheme}, recording in `skipped` when the scheme the import needed has no equivalent. */
+export function authFromScheme(scheme, skipped) {
+    const mapped = mapScheme(scheme);
+    if (mapped.auth === undefined) {
+        skipped.push({
+            kind: 'security-scheme',
+            where: scheme.name,
+            reason: mapped.reason ?? 'Not supported',
+        });
+    }
+    return mapped.auth;
+}
+/** The scheme a requirement names, when it names exactly one this client can use. */
+function schemeOfRequirement(requirements, schemes) {
+    const names = Object.keys(requirements?.[0] ?? {});
+    const first = names[0];
+    return first === undefined ? undefined : schemes.find((scheme) => scheme.name === first);
+}
+/** A request's own credentials, set only where the operation departs from the document's default. */
+function operationAuth(operation, document, skipped) {
+    if (operation.security === undefined) {
+        return undefined;
+    }
+    if (operation.security.length === 0) {
+        // "Explicitly unauthenticated" is a statement, and `none` is how this client says it.
+        return { type: 'none' };
+    }
+    const own = schemeOfRequirement(operation.security, document.securitySchemes);
+    const global = schemeOfRequirement(document.security, document.securitySchemes);
+    if (own === undefined || own.name === global?.name) {
+        return undefined;
+    }
+    return authFromScheme(own, skipped);
+}
+/** The first segment of a path, which is the folder a tagless operation falls into. */
+function firstPathSegment(path) {
+    for (const segment of path.split('/')) {
+        if (segment.length > 0 && !segment.startsWith('{')) {
+            return segment;
+        }
+    }
+    return undefined;
+}
+/** The folder an operation belongs in: its first tag, else `Deprecated`, else its first path segment. */
+function folderNameOf(operation) {
+    const tag = operation.tags?.[0];
+    if (tag !== undefined && tag.length > 0) {
+        // A tag is the document's own answer, and it wins even for a deprecated operation: the author
+        // filed it with its live siblings, and moving it would hide a rename the user has to make.
+        return tag;
+    }
+    // Untagged and deprecated is the operation that would otherwise be lost among the live ones in a
+    // path-segment folder, so this is where `Deprecated` earns its keep.
+    if (operation.deprecated === true) {
+        return 'Deprecated';
+    }
+    return firstPathSegment(operation.path);
+}
+/** A request's name: its summary, else its operation id, else what it does. */
+function requestName(operation) {
+    const summary = operation.summary?.trim();
+    if (summary !== undefined && summary.length > 0) {
+        return summary;
+    }
+    if (operation.operationId !== undefined && operation.operationId.length > 0) {
+        return operation.operationId;
+    }
+    const method = HTTP_METHODS.includes(operation.method.toLowerCase())
+        ? operation.method.toUpperCase()
+        : operation.method;
+    return `${method} ${operation.path}`;
+}
+/** A request's description, with a deprecation marked where the operation says so. */
+function requestDescription(operation) {
+    const body = operation.description?.trim();
+    if (operation.deprecated !== true) {
+        return body !== undefined && body.length > 0 ? body : undefined;
+    }
+    return body !== undefined && body.length > 0 ? `**Deprecated.**\n\n${body}` : '**Deprecated.**';
+}
+/** Operations grouped by folder name, each group in document order, groups in first-met order. */
+function groupByFolder(operations) {
+    const groups = new Map();
+    for (const operation of operations) {
+        const name = folderNameOf(operation);
+        const group = groups.get(name);
+        if (group === undefined) {
+            groups.set(name, [operation]);
+        }
+        else {
+            group.push(operation);
+        }
+    }
+    return groups;
+}
+/**
+ * Maps a parsed document onto one API.
+ *
+ * @param document a document already parsed and `$ref`-resolved (see `import.ts`)
+ * @returns the API, and a summary of what the mapping used and what it could not
+ */
+export function apiFromDocument(document, options = {}) {
+    const newId = options.newId ?? generateId;
+    const skipped = [...document.skipped];
+    const servers = document.servers.map((server) => ({
+        url: serverUrl(server),
+        ...(server.description !== undefined ? { description: server.description } : {}),
+    }));
+    const title = document.info.title.trim();
+    const name = options.name?.trim() ?? (title.length > 0 ? title : 'API');
+    const baseUrl = options.baseUrl ?? servers[0]?.url ?? '';
+    const chosenScheme = options.securityScheme !== undefined
+        ? document.securitySchemes.find((scheme) => scheme.name === options.securityScheme)
+        : document.security?.length === 1
+            ? schemeOfRequirement(document.security, document.securitySchemes)
+            : undefined;
+    const apiAuth = chosenScheme === undefined ? undefined : authFromScheme(chosenScheme, skipped);
+    const tagDescriptions = new Map(document.tags.map((tag) => [tag.name, tag.description]));
+    const groups = groupByFolder(document.operations);
+    const rootRequests = [];
+    const folders = [];
+    const folderSlugs = new Set();
+    const rootSlugs = new Set();
+    let deprecated = 0;
+    let requests = 0;
+    const buildRequest = (operation, order, taken) => {
+        noteCookieParameters(operation, skipped);
+        if (operation.deprecated === true) {
+            deprecated += 1;
+        }
+        requests += 1;
+        const label = requestName(operation);
+        const auth = operationAuth(operation, document, skipped);
+        const description = requestDescription(operation);
+        return createRestRequest(label, {
+            id: newId(),
+            slug: uniqueSlug(label, taken),
+            order,
+            method: HTTP_METHODS.includes(operation.method.toLowerCase()) ? operation.method.toUpperCase() : operation.method,
+            url: operation.path,
+            ...(description !== undefined ? { description } : {}),
+            pathParams: parameterRows(operation, 'path', options, skipped),
+            query: parameterRows(operation, 'query', options, skipped),
+            headers: parameterRows(operation, 'header', options, skipped),
+            body: bodyOf(operation, options, skipped),
+            ...(auth !== undefined ? { auth } : {}),
+        });
+    };
+    for (const [folderName, operations] of groups) {
+        if (folderName === undefined) {
+            operations.forEach((operation, index) => {
+                const request = buildRequest(operation, index, rootSlugs);
+                rootSlugs.add(request.slug);
+                rootRequests.push(request);
+            });
+            continue;
+        }
+        const taken = new Set();
+        const inside = operations.map((operation, index) => {
+            const request = buildRequest(operation, index, taken);
+            taken.add(request.slug);
+            return request;
+        });
+        const description = tagDescriptions.get(folderName);
+        const slug = uniqueSlug(folderName, folderSlugs);
+        folderSlugs.add(slug);
+        folders.push(createFolder(folderName, {
+            id: newId(),
+            slug,
+            order: folders.length,
+            ...(description !== undefined ? { description } : {}),
+            requests: inside,
+        }));
+    }
+    const api = createApi(name, {
+        id: newId(),
+        slug: slugify(name),
+        order: options.order ?? 0,
+        baseUrl,
+        servers,
+        ...(document.info.description !== undefined ? { description: document.info.description } : {}),
+        ...(apiAuth !== undefined ? { auth: apiAuth } : {}),
+        ...(options.definition !== undefined ? { definition: options.definition } : {}),
+        folders,
+        requests: rootRequests,
+    });
+    return {
+        api,
+        summary: {
+            name,
+            title,
+            declaredVersion: document.declaredVersion,
+            ...(document.info.version !== undefined ? { apiVersion: document.info.version } : {}),
+            baseUrl,
+            servers,
+            folders: folders.length,
+            requests,
+            deprecated,
+            ...(apiAuth !== undefined ? { auth: apiAuth.type } : {}),
+            securitySchemes: document.securitySchemes.map((scheme) => {
+                const mapped = mapScheme(scheme);
+                return {
+                    name: scheme.name,
+                    type: scheme.type,
+                    ...(scheme.description !== undefined ? { description: scheme.description } : {}),
+                    ...(mapped.auth !== undefined ? { auth: mapped.auth } : {}),
+                    ...(mapped.reason !== undefined ? { reason: mapped.reason } : {}),
+                    applied: scheme.name === chosenScheme?.name,
+                };
+            }),
+            skipped: uniqueSkipped(skipped),
+        },
+    };
+}
+/**
+ * The skipped list without repeats. A scheme this client cannot map is met once per operation
+ * that names it — twenty operations behind one implicit flow would otherwise say the same thing
+ * twenty times, and the summary is for reading.
+ */
+function uniqueSkipped(skipped) {
+    const seen = new Set();
+    return skipped.filter((entry) => {
+        const key = `${entry.kind}\u0000${entry.where}\u0000${entry.reason}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}

package/dist/rest/openapi/model.d.ts

@@ -0,0 +1,203 @@
+/**
+ * The subset of OpenAPI 3.0.x and 3.1.x this client consumes, as readonly types.
+ *
+ * Deliberately a *subset*: an import turns a description into requests you can send, so the model
+ * carries what decides a request — where it goes, what it carries, and what it authenticates with —
+ * and nothing else. Everything else a document says (callbacks, links, webhooks, vendor extensions)
+ * is kept only as a count, so the import summary can say what it did not understand rather than
+ * quietly dropping it.
+ *
+ * Every field is optional where the specification allows it, because a document in the wild will
+ * omit anything that is not required, and a parser that insists otherwise refuses documents users
+ * legitimately have.
+ */
+/** A JSON value, as a document literally contains it (an `example`, a `default`, an `enum` member). */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/** Which specification version a document declares. */
+export type OpenApiVersion = '1.0' | '1.1' | '1.2' | '2.0' | '3.0' | '3.1' | '3.2';
+/** `info`: what the API is called, and which version of *it* this document describes. */
+export interface OpenApiInfo {
+    readonly title: string;
+    readonly version?: string;
+    readonly description?: string;
+}
+/** One `servers` entry, with the variables its template names. */
+export interface OpenApiServer {
+    readonly url: string;
+    readonly description?: string;
+    readonly variables?: Readonly<Record<string, OpenApiServerVariable>>;
+}
+/**
+ * One server-template variable: its default, and the values it is allowed to take.
+ *
+ * `default` is required by the specification but routinely omitted in the wild, and a variable with
+ * none has nothing to substitute — so it is optional here, and {@link serverUrl} leaves the template
+ * in place for it rather than collapsing the URL to `https://.api.test`.
+ */
+export interface OpenApiServerVariable {
+    readonly default?: string;
+    readonly enum?: readonly string[];
+    readonly description?: string;
+}
+/** Where a parameter travels. `cookie` is modelled so the import can say it skipped one. */
+export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie';
+/** One parameter, after `$ref` resolution. */
+export interface OpenApiParameter {
+    readonly name: string;
+    readonly in: ParameterLocation;
+    readonly required?: boolean;
+    readonly deprecated?: boolean;
+    readonly description?: string;
+    readonly schema?: JsonSchema;
+    readonly example?: JsonValue;
+    readonly examples?: Readonly<Record<string, OpenApiExample>>;
+    /** How an array or object parameter is serialised; carried so the import can note what it ignored. */
+    readonly style?: string;
+    readonly explode?: boolean;
+}
+/** One named example, either inline or (unsupported here) external. */
+export interface OpenApiExample {
+    readonly value?: JsonValue;
+    readonly summary?: string;
+    readonly externalValue?: string;
+    /** OpenAPI 3.2: structured data value, distinct from raw/serialized format. */
+    readonly dataValue?: JsonValue;
+    /** OpenAPI 3.2: serialized string representation of the example. */
+    readonly serializedValue?: string;
+}
+/** One media type of a request or response body. */
+export interface OpenApiMediaType {
+    readonly schema?: JsonSchema;
+    /** OpenAPI 3.2: item schema for sequential/streaming media types (e.g. text/event-stream). */
+    readonly itemSchema?: JsonSchema;
+    readonly example?: JsonValue;
+    readonly examples?: Readonly<Record<string, OpenApiExample>>;
+}
+/** A request body: its media types, and whether the operation insists on one. */
+export interface OpenApiRequestBody {
+    readonly required?: boolean;
+    readonly description?: string;
+    readonly content: Readonly<Record<string, OpenApiMediaType>>;
+}
+/**
+ * The JSON Schema subset the sample generator reads — Draft 2020-12 as 3.1 uses it, and 3.0's own
+ * dialect, which differs in the two ways noted on the fields.
+ */
+export interface JsonSchema {
+    /** 3.0 allows one type; 3.1 allows a list, which is how it spells "nullable". */
+    readonly type?: string | readonly string[];
+    readonly format?: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly default?: JsonValue;
+    readonly example?: JsonValue;
+    /** 3.1 spelling; 3.0 uses `example`. Both are read. */
+    readonly examples?: readonly JsonValue[];
+    readonly enum?: readonly JsonValue[];
+    readonly const?: JsonValue;
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly required?: readonly string[];
+    readonly items?: JsonSchema;
+    readonly additionalProperties?: boolean | JsonSchema;
+    readonly allOf?: readonly JsonSchema[];
+    readonly oneOf?: readonly JsonSchema[];
+    readonly anyOf?: readonly JsonSchema[];
+    /** 3.0 only: 3.1 spells this as a `type` list including `'null'`. */
+    readonly nullable?: boolean;
+    readonly deprecated?: boolean;
+    readonly readOnly?: boolean;
+    readonly writeOnly?: boolean;
+    /** The `xml` object an XML body's shape honours. */
+    readonly xml?: OpenApiXml;
+    /** Left in place when a reference could not be resolved, so a sample can say so rather than guess. */
+    readonly $ref?: string;
+}
+/** The `xml` object: how a schema's value is spelled as XML. */
+export interface OpenApiXml {
+    readonly name?: string;
+    readonly namespace?: string;
+    readonly prefix?: string;
+    readonly attribute?: boolean;
+    readonly wrapped?: boolean;
+}
+/** One operation of one path. */
+export interface OpenApiOperation {
+    /** Lower-case HTTP method, as the document's key spells it. */
+    readonly method: string;
+    /** The templated path, exactly as the document writes it, `{braces}` and all. */
+    readonly path: string;
+    readonly operationId?: string;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly deprecated?: boolean;
+    /** Path-level and operation-level parameters merged, the operation's winning on name and location. */
+    readonly parameters: readonly OpenApiParameter[];
+    readonly requestBody?: OpenApiRequestBody;
+    /** An operation's own security requirements; an empty array means "explicitly unauthenticated". */
+    readonly security?: readonly OpenApiSecurityRequirement[];
+}
+/** One security requirement: scheme name to the scopes it needs. */
+export type OpenApiSecurityRequirement = Readonly<Record<string, readonly string[]>>;
+/** One `securitySchemes` entry. */
+export interface OpenApiSecurityScheme {
+    /** The name the document files it under, which is what a requirement refers to. */
+    readonly name: string;
+    readonly type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect' | 'mutualTLS';
+    readonly description?: string;
+    /** `http`: the scheme, lower-cased — `basic`, `bearer`, anything else. */
+    readonly scheme?: string;
+    readonly bearerFormat?: string;
+    /** `apiKey`: the parameter's name and where it travels. */
+    readonly in?: ParameterLocation;
+    readonly keyName?: string;
+    /** `oauth2`: the flows the document offers, by name. */
+    readonly flows?: Readonly<Record<string, OpenApiOAuthFlow>>;
+}
+/** One OAuth2 flow. */
+export interface OpenApiOAuthFlow {
+    readonly authorizationUrl?: string;
+    readonly tokenUrl?: string;
+    readonly refreshUrl?: string;
+    readonly scopes?: Readonly<Record<string, string>>;
+}
+/** One `tags` entry, for a folder's description. */
+export interface OpenApiTag {
+    readonly name: string;
+    readonly description?: string;
+}
+/** What a parser could not use, so the summary can report it rather than the import losing it silently. */
+export interface OpenApiSkipped {
+    /** What kind of thing was skipped — `operation`, `parameter`, `callback`, `webhook`, `extension`… */
+    readonly kind: string;
+    /** Where it was, as a JSON pointer or a `METHOD /path` — enough for the user to find it. */
+    readonly where: string;
+    readonly reason: string;
+}
+/** The document, as this client understands it. */
+export interface OpenApiDocument {
+    readonly version: OpenApiVersion;
+    /** The exact `openapi` string the document declared, for the definition card. */
+    readonly declaredVersion: string;
+    readonly info: OpenApiInfo;
+    readonly servers: readonly OpenApiServer[];
+    /** Every operation of every path, in document order. */
+    readonly operations: readonly OpenApiOperation[];
+    readonly securitySchemes: readonly OpenApiSecurityScheme[];
+    /** The document-level security requirements, when it declares any. */
+    readonly security?: readonly OpenApiSecurityRequirement[];
+    readonly tags: readonly OpenApiTag[];
+    /** Everything the model does not carry, counted and located. */
+    readonly skipped: readonly OpenApiSkipped[];
+}
+/** The HTTP methods an operation key may name, per OpenAPI's Path Item Object. */
+export declare const HTTP_METHODS: readonly string[];
+/**
+ * The base URL a server entry resolves to, with each `{variable}` replaced by its default.
+ *
+ * A variable with no default is left as it is: the API's base URL then still shows the template,
+ * which is honest — the user has to decide what it should be, and the field is editable.
+ */
+export declare function serverUrl(server: OpenApiServer): string;