@wirebench/engine 2.2.1 → 3.1.0-rc.1

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

@@ -7,24 +7,13 @@
  * importOpenApi} then adds the mapping from `map.ts`, so a caller that already has the text (a
  * re-import from the cache, a test) can do either half on its own.
  */
-import type { FetchDocument } from '../../wsdl/resolver.js';
+import type { FetchDocument } from '../../http/fetch-document.js';
+import type { OpenApiSource } from '../../json/schema/source.js';
+import type { WebhookFolder } from '../../webhooks/model.js';
 import type { MapApiOptions, MappedApi } from './map.js';
 import type { OpenApiDocument } from './model.js';
-import { type RefProblem, type ResolvedDocument } from './refs.js';
-/** Where a document comes from: a location to fetch, or text the user already has. */
-export type OpenApiSource = {
-    readonly kind: 'url';
-    readonly url: string;
-} | {
-    readonly kind: 'file';
-    readonly path: string;
-}
-/** Text with a location to resolve relative references against — a paste, or a test. */
- | {
-    readonly kind: 'text';
-    readonly text: string;
-    readonly location?: string;
-};
+import { type RefProblem, type ResolvedDocument } from '../../json/schema/refs.js';
+export type { OpenApiSource };
 export interface ParseOpenApiOptions {
     readonly fetchDocument: FetchDocument;
     readonly signal?: AbortSignal;
@@ -46,6 +35,10 @@ export interface ParsedOpenApi {
 export declare function parseOpenApi(source: OpenApiSource, options: ParseOpenApiOptions): Promise<ParsedOpenApi>;
 /** Options for {@link importOpenApi}: how to fetch, and how to map what was fetched. */
 export interface ImportOpenApiOptions extends ParseOpenApiOptions, MapApiOptions {
+    /** Also map the document's webhooks and callbacks into a group. Defaults to `true`. */
+    readonly webhooks?: boolean;
+    /** The id the webhook group links back to. Defaults to the imported API's own id. */
+    readonly apiId?: string;
 }
 /** An imported API, every document it was made of, and what the mapping could not use. */
 export interface ImportedOpenApi extends MappedApi {
@@ -55,6 +48,8 @@ export interface ImportedOpenApi extends MappedApi {
     readonly refProblems: readonly RefProblem[];
     /** The document itself, for a caller that wants to offer a choice and map again. */
     readonly document: OpenApiDocument;
+    /** The document's webhooks and callbacks, mapped into one group, when there were any to map. */
+    readonly webhooks?: WebhookFolder;
 }
 /**
  * Fetches, resolves, parses and maps one OpenAPI document into an API.

package/dist/rest/openapi/import.js

@@ -8,9 +8,9 @@
  * re-import from the cache, a test) can do either half on its own.
  */
 import { OpenApiError } from '../../errors.js';
-import { apiFromDocument } from './map.js';
+import { apiFromDocument, webhooksFromDocument } from './map.js';
 import { parseOpenApiDocument } from './parse.js';
-import { resolveRefs } from './refs.js';
+import { resolveRefs } from '../../json/schema/refs.js';
 /** The absolute location a source resolves references against. */
 function locationOf(source) {
     if (source.kind === 'url') {
@@ -73,8 +73,11 @@ export async function parseOpenApi(source, options) {
 export async function importOpenApi(source, options) {
     const parsed = await parseOpenApi(source, options);
     const mapped = apiFromDocument(parsed.document, options);
+    const webhookOptions = { ...options, apiId: options.apiId ?? mapped.api.id };
+    const hooks = options.webhooks === false ? undefined : webhooksFromDocument(parsed.document, webhookOptions);
     const skipped = [
         ...mapped.summary.skipped,
+        ...(hooks?.skipped ?? []),
         ...parsed.refProblems.map((problem) => ({
             kind: 'reference',
             where: problem.at,
@@ -87,5 +90,6 @@ export async function importOpenApi(source, options) {
         documents: parsed.documents,
         refProblems: parsed.refProblems,
         document: parsed.document,
+        ...(hooks !== undefined ? { webhooks: hooks.folder } : {}),
     };
 }

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

@@ -12,8 +12,10 @@
  * the summary rather than dropped in silence.
  */
 import type { AuthConfig, IdGenerator } from '../../project/model.js';
+import type { HookLink } from '../../webhooks/model.js';
+import { type WebhookFolder } from '../../webhooks/model.js';
 import type { RestApi, RestDefinitionRef, RestServer } from '../model.js';
-import type { OpenApiDocument, OpenApiSecurityScheme, OpenApiSkipped } from './model.js';
+import type { OpenApiDocument, OpenApiOperation, OpenApiSecurityScheme, OpenApiSkipped } from './model.js';
 /** How the caller wants the document read. Every field has a documented default. */
 export interface MapApiOptions {
     /** The API's name. Defaults to `info.title`, which the import dialog offers for editing. */
@@ -68,6 +70,8 @@ export interface OpenApiImportSummary {
     readonly folders: number;
     readonly requests: number;
     readonly deprecated: number;
+    /** Every webhook and callback method the document offers, whether or not this import maps them. */
+    readonly webhooks: number;
     /** The auth the API ended up with, by type, when it got any. */
     readonly auth?: AuthConfig['type'];
     /** Every scheme the document declares, so the dialog can offer a different one. */
@@ -93,6 +97,39 @@ export declare function mapScheme(scheme: OpenApiSecurityScheme): {
 };
 /** {@link mapScheme}, recording in `skipped` when the scheme the import needed has no equivalent. */
 export declare function authFromScheme(scheme: OpenApiSecurityScheme, skipped: OpenApiSkipped[]): AuthConfig | undefined;
+/** One webhook or callback method a document offers, keyed as *Update definition* matches it. */
+export interface WebhookItemRef {
+    readonly key: string;
+    readonly kind: 'webhook' | 'callback';
+    readonly name: string;
+    readonly method: string;
+    readonly operation?: string;
+    readonly expression?: string;
+    readonly label: string;
+}
+/** A document's webhook and callback methods with their operations. Internal to the OpenAPI modules. */
+export declare function webhookSourcesOf(document: OpenApiDocument): {
+    readonly ref: WebhookItemRef;
+    readonly operation: OpenApiOperation;
+    readonly link: HookLink;
+    /** The item's own name for the first method, `name (METHOD)` for a later one — no parent label. */
+    readonly displayName: string;
+}[];
+/** Every webhook and callback method `document` offers, in document order. */
+export declare function webhookItemsOf(document: OpenApiDocument): WebhookItemRef[];
+/** Options for {@link webhooksFromDocument}. */
+export interface MapWebhooksOptions extends MapApiOptions {
+    /** The API the group is linked to. */
+    readonly apiId: string;
+    /** Keys ({@link WebhookItemRef.key}) to keep; all when absent. */
+    readonly only?: ReadonlySet<string>;
+}
+/** The document's webhooks and callbacks as one group for the project's webhook collection. */
+export declare function webhooksFromDocument(document: OpenApiDocument, options: MapWebhooksOptions): {
+    readonly folder: WebhookFolder;
+    readonly items: number;
+    readonly skipped: readonly OpenApiSkipped[];
+} | undefined;
 /**
  * Maps a parsed document onto one API.
  *

package/dist/rest/openapi/map.js

@@ -13,11 +13,12 @@
  */
 import { generateId } from '../../project/model.js';
 import { slugify, uniqueSlug } from '../../project/paths.js';
+import { createWebhookFolder, hookKey } from '../../webhooks/model.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';
+import { sampleFromSchema, sampleXml } from '../../json/schema/sample.js';
 /** Header parameters OpenAPI itself says to ignore, because the message decides them. */
-const RESERVED_HEADERS = new Set(['accept', 'content-type', 'authorization']);
+const RESERVED_HEADERS = new Set(['accept', 'content-type', 'authorization', 'cookie']);
 /** The media types a *Binary* body is the honest reading of. */
 function isBinaryMedia(type, schema) {
     if (schema?.format === 'binary') {
@@ -92,17 +93,26 @@ function parameterRows(operation, location, options, skipped) {
     }
     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`,
-            });
-        }
+/**
+ * Cookie parameters, and an API key the operation's scheme puts in a cookie, as one `Cookie`
+ * header row: this client has no cookie table, and a header is how a cookie travels anyway. Off,
+ * like every imported header, and an API key's value is left blank — secrets are never invented.
+ */
+function cookieHeader(operation, scheme, options) {
+    const pairs = operation.parameters
+        .filter((parameter) => parameter.in === 'cookie')
+        .map((parameter) => `${parameter.name}=${parameterValue(parameter, options)}`);
+    if (scheme?.type === 'apiKey' && scheme.in === 'cookie' && scheme.keyName !== undefined) {
+        pairs.push(`${scheme.keyName}=`);
+    }
+    return pairs.length === 0 ? [] : [entry('Cookie', pairs.join('; '), { enabled: false })];
+}
+/** The scheme an operation is sent under: its own when it states one, else the one the API was given. */
+function effectiveScheme(operation, document, apiScheme) {
+    if (operation.security !== undefined) {
+        return schemeOfRequirement(operation.security, document.securitySchemes);
     }
+    return apiScheme;
 }
 /** The media type an operation's body is built from, under {@link BODY_PREFERENCE}. */
 function preferredMedia(content) {
@@ -218,7 +228,7 @@ export function mapScheme(scheme) {
             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' };
+            return { reason: 'An API key in a cookie is sent as a Cookie header on each request instead' };
         case 'oauth2': {
             const clientCredentials = scheme.flows?.clientCredentials;
             const authorizationCode = scheme.flows?.authorizationCode;
@@ -340,6 +350,122 @@ function groupByFolder(operations) {
     }
     return groups;
 }
+/**
+ * One operation as a request. Shared by an API's own paths and by a webhook group's items —
+ * `overrides` is how the latter departs: its own name and URL, a {@link HookLink} instead of a
+ * `contract`, and no path parameters, since a webhook or callback URL is the caller's to fill in.
+ */
+function requestFromOperation(operation, order, taken, context, overrides) {
+    const { document, options, newId, skipped, counts } = context;
+    if (operation.deprecated === true) {
+        counts.deprecated += 1;
+    }
+    counts.requests += 1;
+    const label = overrides?.name ?? 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: overrides?.url ?? operation.path,
+        ...(description !== undefined ? { description } : {}),
+        pathParams: overrides !== undefined ? [] : parameterRows(operation, 'path', options, skipped),
+        query: parameterRows(operation, 'query', options, skipped),
+        headers: [
+            ...parameterRows(operation, 'header', options, skipped),
+            ...cookieHeader(operation, effectiveScheme(operation, document, context.apiScheme), options),
+        ],
+        body: bodyOf(operation, options, skipped),
+        ...(auth !== undefined ? { auth } : {}),
+        ...(overrides !== undefined
+            ? { hook: overrides.hook }
+            : { contract: { method: operation.method.toLowerCase(), path: operation.path } }),
+    });
+}
+/** A document's webhook and callback methods with their operations. Internal to the OpenAPI modules. */
+export function webhookSourcesOf(document) {
+    const sources = [];
+    const named = (name, method, first) => (first ? name : `${name} (${method.toUpperCase()})`);
+    for (const hook of document.webhooks ?? []) {
+        hook.operations.forEach((operation, index) => {
+            const link = { kind: 'webhook', name: hook.name };
+            const displayName = named(hook.name, operation.method, index === 0);
+            sources.push({
+                operation,
+                link,
+                displayName,
+                ref: {
+                    key: hookKey(link, operation.method),
+                    kind: 'webhook',
+                    name: hook.name,
+                    method: operation.method,
+                    label: displayName,
+                },
+            });
+        });
+    }
+    for (const parent of document.operations) {
+        const parentKey = `${parent.method.toLowerCase()} ${parent.path}`;
+        const parentLabel = parent.operationId ?? `${parent.method.toUpperCase()} ${parent.path}`;
+        for (const callback of parent.callbacks ?? []) {
+            callback.operations.forEach((operation, index) => {
+                const link = {
+                    kind: 'callback',
+                    operation: parentKey,
+                    name: callback.name,
+                    expression: callback.expression,
+                };
+                const displayName = named(callback.name, operation.method, index === 0);
+                sources.push({
+                    operation,
+                    link,
+                    displayName,
+                    ref: {
+                        key: hookKey(link, operation.method),
+                        kind: 'callback',
+                        name: callback.name,
+                        method: operation.method,
+                        operation: parentKey,
+                        expression: callback.expression,
+                        label: `${displayName} · ${parentLabel}`,
+                    },
+                });
+            });
+        }
+    }
+    return sources;
+}
+/** Every webhook and callback method `document` offers, in document order. */
+export function webhookItemsOf(document) {
+    return webhookSourcesOf(document).map((source) => source.ref);
+}
+/** The document's webhooks and callbacks as one group for the project's webhook collection. */
+export function webhooksFromDocument(document, options) {
+    const chosen = webhookSourcesOf(document).filter((source) => options.only?.has(source.ref.key) ?? true);
+    if (chosen.length === 0)
+        return undefined;
+    const newId = options.newId ?? generateId;
+    const context = { document, options, newId, skipped: [], counts: { requests: 0, deprecated: 0 } };
+    const taken = new Set();
+    const requests = chosen.map((source, index) => {
+        const request = requestFromOperation(source.operation, index, taken, context, {
+            name: source.displayName,
+            url: `/${source.ref.name}`,
+            hook: source.link,
+        });
+        taken.add(request.slug);
+        return request;
+    });
+    const title = document.info.title.trim();
+    const name = options.name?.trim() ?? (title.length > 0 ? title : 'API');
+    return {
+        folder: createWebhookFolder(name, { id: newId(), source: { apiId: options.apiId }, requests }),
+        items: requests.length,
+        skipped: context.skipped,
+    };
+}
 /**
  * Maps a parsed document onto one API.
  *
@@ -368,35 +494,18 @@ export function apiFromDocument(document, options = {}) {
     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 } : {}),
-        });
+    const context = {
+        document,
+        options,
+        newId,
+        skipped,
+        counts: { requests: 0, deprecated: 0 },
+        ...(chosenScheme !== undefined ? { apiScheme: chosenScheme } : {}),
     };
     for (const [folderName, operations] of groups) {
         if (folderName === undefined) {
             operations.forEach((operation, index) => {
-                const request = buildRequest(operation, index, rootSlugs);
+                const request = requestFromOperation(operation, index, rootSlugs, context);
                 rootSlugs.add(request.slug);
                 rootRequests.push(request);
             });
@@ -404,7 +513,7 @@ export function apiFromDocument(document, options = {}) {
         }
         const taken = new Set();
         const inside = operations.map((operation, index) => {
-            const request = buildRequest(operation, index, taken);
+            const request = requestFromOperation(operation, index, taken, context);
             taken.add(request.slug);
             return request;
         });
@@ -441,8 +550,9 @@ export function apiFromDocument(document, options = {}) {
             baseUrl,
             servers,
             folders: folders.length,
-            requests,
-            deprecated,
+            requests: context.counts.requests,
+            deprecated: context.counts.deprecated,
+            webhooks: webhookItemsOf(document).length,
             ...(apiAuth !== undefined ? { auth: apiAuth.type } : {}),
             securitySchemes: document.securitySchemes.map((scheme) => {
                 const mapped = mapScheme(scheme);

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

@@ -0,0 +1,20 @@
+/**
+ * Finding the operation of a definition a request calls, from its method and URL alone.
+ *
+ * Variables cannot be expanded here, so a `{{…}}` or `${…}` in the URL is opaque: at the start it
+ * stands for a base URL, and as a whole segment it matches any segment, as a `{param}` does. Pure,
+ * so the importer, the editor and the tests share it.
+ */
+/** An operation as the definition names it: the lower-case method and the templated path. */
+export interface RestOperationRef {
+    readonly method: string;
+    readonly path: string;
+}
+/**
+ * The one operation `method` and `url` call. As in OpenAPI, a concrete path wins over a templated
+ * one: of several matches, the one with the most literal segments; `undefined` on a tie or no match.
+ * A URL whose host matches no server still matches by path, once its origin is dropped and, if it
+ * starts with one, a server's own path prefix.
+ * `baseUrls` are the API's servers and base URL; the longest one the URL starts with is stripped.
+ */
+export declare function matchOperation(operations: readonly RestOperationRef[], method: string, url: string, baseUrls: readonly string[]): RestOperationRef | undefined;

package/dist/rest/openapi/match.js

@@ -0,0 +1,117 @@
+/**
+ * Finding the operation of a definition a request calls, from its method and URL alone.
+ *
+ * Variables cannot be expanded here, so a `{{…}}` or `${…}` in the URL is opaque: at the start it
+ * stands for a base URL, and as a whole segment it matches any segment, as a `{param}` does. Pure,
+ * so the importer, the editor and the tests share it.
+ */
+const VARIABLE = /^(?:\{\{[^}]*\}\}|\$\{[^}]*\}|\{[^}]*\})$/;
+const LEADING_VARIABLE = /^(?:\{\{[^}]*\}\}|\$\{[^}]*\})/;
+const ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*/i;
+function withoutQuery(url) {
+    const end = url.search(/[?#]/);
+    return end === -1 ? url : url.slice(0, end);
+}
+/** `value` without trailing slashes; a loop, since `/\/+$/` backtracks on a long run of them. */
+function trimSlash(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47 /* '/' */) {
+        end -= 1;
+    }
+    return value.slice(0, end);
+}
+/** The URL's path relative to the API: the longest matching base URL, a leading variable, or the origin gone. */
+function relativePath(url, baseUrls) {
+    const bases = baseUrls
+        .map((base) => trimSlash(withoutQuery(base.trim())))
+        .filter((base) => base.length > 0)
+        .sort((a, b) => b.length - a.length);
+    for (const base of bases) {
+        if (url === base || url.startsWith(`${base}/`)) {
+            return url.slice(base.length);
+        }
+    }
+    const variable = LEADING_VARIABLE.exec(url);
+    if (variable !== null) {
+        return url.slice(variable[0].length);
+    }
+    const origin = ORIGIN.exec(url);
+    const path = origin === null ? url : url.slice(origin[0].length);
+    // No base matched whole, as when the URL is sent to another host (staging, a mock) than the
+    // servers name: a base's own path prefix (`/v1`) is still not part of the operation's path.
+    const prefixes = bases
+        .map((base) => basePath(base))
+        .filter((prefix) => prefix.length > 0)
+        .sort((a, b) => b.length - a.length);
+    for (const prefix of prefixes) {
+        if (path === prefix || path.startsWith(`${prefix}/`)) {
+            return path.slice(prefix.length);
+        }
+    }
+    return path;
+}
+/** A base URL's path after its origin, or after a leading variable standing for one (`{scheme}://…` stays opaque). */
+function basePath(base) {
+    const origin = ORIGIN.exec(base) ?? LEADING_VARIABLE.exec(base);
+    if (origin !== null)
+        return trimSlash(base.slice(origin[0].length));
+    return base.startsWith('/') ? trimSlash(base) : '';
+}
+function segments(path) {
+    return path.split('/').filter((segment) => segment.length > 0);
+}
+function decoded(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+/** How many of `declared`'s segments are literal when it matches `actual`, or -1 when it does not. */
+function literalMatch(declared, actual) {
+    if (declared.length !== actual.length) {
+        return -1;
+    }
+    let literals = 0;
+    for (const [index, segment] of declared.entries()) {
+        const other = actual[index];
+        if (VARIABLE.test(segment) || VARIABLE.test(other)) {
+            continue;
+        }
+        if (decoded(segment) !== decoded(other)) {
+            return -1;
+        }
+        literals += 1;
+    }
+    return literals;
+}
+/**
+ * The one operation `method` and `url` call. As in OpenAPI, a concrete path wins over a templated
+ * one: of several matches, the one with the most literal segments; `undefined` on a tie or no match.
+ * A URL whose host matches no server still matches by path, once its origin is dropped and, if it
+ * starts with one, a server's own path prefix.
+ * `baseUrls` are the API's servers and base URL; the longest one the URL starts with is stripped.
+ */
+export function matchOperation(operations, method, url, baseUrls) {
+    const actual = segments(withoutQuery(relativePath(url.trim(), baseUrls)));
+    const wanted = method.toLowerCase();
+    let best;
+    let bestLiterals = -1;
+    let tied = false;
+    for (const operation of operations) {
+        if (operation.method.toLowerCase() !== wanted) {
+            continue;
+        }
+        const literals = literalMatch(segments(operation.path), actual);
+        if (literals > bestLiterals) {
+            best = operation;
+            bestLiterals = literals;
+            tied = false;
+        }
+        else if (literals >= 0 && literals === bestLiterals) {
+            tied = true;
+        }
+    }
+    return best === undefined || tied ? undefined : { method: best.method, path: best.path };
+}

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

@@ -11,10 +11,8 @@
  * 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;
-};
+import type { JsonSchema, JsonValue, OpenApiXml } from '../../json/schema/model.js';
+export type { JsonSchema, JsonValue, OpenApiXml };
 /** 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. */
@@ -81,47 +79,6 @@ export interface OpenApiRequestBody {
     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. */
@@ -138,7 +95,36 @@ export interface OpenApiOperation {
     readonly requestBody?: OpenApiRequestBody;
     /** An operation's own security requirements; an empty array means "explicitly unauthenticated". */
     readonly security?: readonly OpenApiSecurityRequirement[];
+    /** The declared responses, keyed as the document keys them (`'200'`, `'4XX'`, `'default'`). */
+    readonly responses?: OpenApiResponses;
+    /** This operation's `callbacks`, when it declares any. */
+    readonly callbacks?: readonly OpenApiCallback[];
+}
+/** A root `webhooks` entry (OpenAPI 3.1+): its name and one operation per method. */
+export interface OpenApiHook {
+    readonly name: string;
+    /** Each operation's `path` is the hook's name; `method` is lower-case. */
+    readonly operations: readonly OpenApiOperation[];
+}
+/** One `callbacks` entry of an operation: its name, its path-item key, and that item's operations. */
+export interface OpenApiCallback {
+    readonly name: string;
+    /** The path-item key verbatim, e.g. `{$request.body#/callbackUrl}`. */
+    readonly expression: string;
+    /** Each operation's `path` is the expression. */
+    readonly operations: readonly OpenApiOperation[];
+}
+/** One declared response media type. The schema is the `$ref`-resolved node, kept as plain data. */
+export interface OpenApiResponseMediaType {
+    readonly schema?: unknown;
+}
+/** One declared response. No `content` means the contract declares no body. */
+export interface OpenApiResponse {
+    readonly description?: string;
+    readonly content?: Readonly<Record<string, OpenApiResponseMediaType>>;
 }
+/** An operation's responses, keyed by status (`'200'`), range (`'4XX'`) or `'default'`. */
+export type OpenApiResponses = Readonly<Record<string, OpenApiResponse>>;
 /** One security requirement: scheme name to the scopes it needs. */
 export type OpenApiSecurityRequirement = Readonly<Record<string, readonly string[]>>;
 /** One `securitySchemes` entry. */
@@ -189,6 +175,8 @@ export interface OpenApiDocument {
     /** The document-level security requirements, when it declares any. */
     readonly security?: readonly OpenApiSecurityRequirement[];
     readonly tags: readonly OpenApiTag[];
+    /** Root `webhooks` entries (OpenAPI 3.1+), when the document declares any. */
+    readonly webhooks?: readonly OpenApiHook[];
     /** Everything the model does not carry, counted and located. */
     readonly skipped: readonly OpenApiSkipped[];
 }

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

@@ -8,21 +8,13 @@
  * YAML, and a document that does not declare a supported OpenAPI or Swagger version. Swagger 1.x
  * and 2.0 documents are converted into the intermediate OpenAPI representation.
  *
- * The parser reads a document that is already resolved: `refs.ts` inlines every `$ref` first, so
+ * The parser reads a document that is already resolved: `json/schema/refs.ts` inlines every `$ref` first, so
  * nothing here has to fetch anything.
  */
 import type { JsonSchema, OpenApiDocument, OpenApiVersion } from './model.js';
 /** A plain object, which is all this parser ever walks into. */
 type Record_ = Readonly<Record<string, unknown>>;
-/**
- * Parses text as JSON when it looks like JSON, and as YAML otherwise.
- *
- * JSON is a subset of YAML, so one parser would do — but a JSON document with a syntax error gets a
- * far better message from `JSON.parse`, and that message is what the user has to act on.
- *
- * @throws OpenApiError `openapi-malformed` when the text parses as neither.
- */
-export declare function parseDocumentText(text: string, where?: string): unknown;
+export { parseDocumentText } from '../../json/schema/parse-text.js';
 /**
  * The version a document declares, as a major-minor this client supports.
  *
@@ -36,9 +28,8 @@ export declare function versionOf(root: unknown): {
 /**
  * Reads a resolved OpenAPI document.
  *
- * @param root the parsed document, with every `$ref` already inlined (see `refs.ts`)
+ * @param root the parsed document, with every `$ref` already inlined (see `json/schema/refs.ts`)
  * @throws OpenApiError `openapi-not-a-document` / `openapi-unsupported-version` as {@link versionOf} does
  */
 export declare function parseOpenApiDocument(root: unknown): OpenApiDocument;
 export declare function parseSchema(value: Record_): JsonSchema;
-export {};