@sezzlee/openapi 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaan Akın
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @sezzlee/openapi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Turns a Swagger 2.0 or OpenAPI 3.0–3.2 document into the same `EndpointDescriptor[]` shape sezzlee's
+catalog builds from framework discovery. This is the ingestion library; everything after the
+descriptor — naming, selection, curation, template production, composition, error mapping, search
+— is the existing catalog and lives elsewhere. The one consumer today is
+[`@sezzlee/openapi-mcp`](../../servers/openapi-mcp).
+
+> Status: `0.2.0`, alpha. Normative source: [openapi-ingestion.md](../spec/openapi-ingestion.md).
+
+## Usage
+
+```ts
+import { ingest } from "@sezzlee/openapi";
+
+const result = await ingest(documentTextOrObject, {
+  documentUrl: "file:///abs/path/to/openapi.json",
+  baseUrl: "https://api.example.com",
+  strict: false,
+});
+
+if (result.fatal) {
+  // result.diagnostics holds at least one "fatal" entry
+}
+```
+
+### `ingest(source, options?)`
+
+`source` is either the document's raw text (JSON or YAML) or an already-parsed `JsonObject`.
+`options` (`IngestOptions`, from `src/ingest.ts`):
+
+| Option                | Type                               | Default                | Notes                                                                                                     |
+| --------------------- | ---------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| `documentUrl`         | `string`                           | —                      | Where the document was read from; relative servers and external `$ref`s resolve against it                |
+| `baseUrl`             | `string`                           | —                      | Replaces the document's root `servers`                                                                    |
+| `serverVariables`     | `Readonly<Record<string, string>>` | —                      | Overrides for server variable defaults                                                                    |
+| `loader`              | `DocumentLoader`                   | —                      | Reads an external `$ref`; without one, a document that has any is refused (`external_ref_blocked`, fatal) |
+| `strict`              | `boolean`                          | `false`                | Raises `openapi_document_invalid` from a warning to a fatal diagnostic                                    |
+| `cookieDenyList`      | `RegExp`                           | the built-in deny-list | Cookie names treated as identity carriers even when no security scheme declares them                      |
+| `identityCookies`     | `readonly string[]`                | `[]`                   | Exact cookie names added to the deny-list (case-insensitive); they extend it and never replace it         |
+| `outputSchema`        | `"document"` \| `"omit"`           | `"document"`           | `omit` for a backend whose responses do not match its document                                            |
+| `hoistPathPrefix`     | `string`                           | —                      | A leading path segment moved from every route into the base URL                                           |
+| `requestBodyRequired` | `"document"` \| `"always"`         | `"document"`           | `always` treats an undeclared `requestBody.required` as `true`                                            |
+
+`ingest` returns an `IngestionResult`:
+
+| Field         | Type                             | Meaning                                                            |
+| ------------- | -------------------------------- | ------------------------------------------------------------------ |
+| `endpoints`   | `readonly SourcedEndpoint[]`     | Empty when `fatal` is `true`                                       |
+| `rootBaseUrl` | `string \| undefined`            | The resolved root server, or the `baseUrl` option that replaced it |
+| `security`    | `SecurityModel`                  | The document's security schemes, keyed by scheme name              |
+| `diagnostics` | `readonly IngestionDiagnostic[]` | Every diagnostic produced, fatal or not                            |
+| `fatal`       | `boolean`                        | `true` when at least one diagnostic is `"fatal"`                   |
+
+## No I/O
+
+`ingest` performs no network or filesystem access itself: `node:http`, `node:https`, `node:net`,
+`node:tls`, `node:fs`, `node:fs/promises`, `undici`, `node-fetch`, `axios`, and the global `fetch`,
+`WebSocket` and `EventSource` are all lint-banned across `src/` (`oxlint.config.ts`). Reading the
+document itself is the caller's job; reading an **external** `$ref` (another file or a URL the
+document points to) is done only through the `loader` a caller injects:
+
+```ts
+export type DocumentLoader = (url: URL) => Promise<string>;
+```
+
+Without a `loader` (and a `documentUrl` to resolve relative references against), a document that
+contains any external `$ref` is refused with `external_ref_blocked` rather than read — ingestion
+never decides on its own which file or host it may reach; that decision belongs to the host. A
+loader is expected to enforce its own limits (an allowlisted host, a deadline, a size cap, a root
+directory for a file); `@sezzlee/openapi-mcp`'s loader is one example, restricted to the document's
+own host plus its configured `refHosts`, with a 64 MiB cap.
+
+## Diagnostics
+
+Every construct the document contains that ingestion cannot represent produces a diagnostic
+instead of throwing — only the `loader`'s own I/O can reject. A diagnostic (`IngestionDiagnostic`,
+`src/diagnostics.ts`) carries:
+
+- `code` — one of the `IngestionCode` values (`openapi_document_unparseable`,
+  `external_ref_blocked`, `unsupported_media_type`, `identity_cookie_parameter`, …; the full list
+  and each code's severity is in [openapi-ingestion.md](../spec/openapi-ingestion.md#diagnostics))
+- `severity` — one of three: `"fatal"` (stops the catalog), `"endpointDropped"` (removes one
+  operation), `"warning"` (changes nothing the agent can reach)
+- `at` — an RFC 6901 `JsonPointer` into the **original** document
+- `message` — human-readable, addressed to the document's author
+
+`ingestionSeverities` (exported from the package) is `as const satisfies Readonly<Record<string,
+CatalogSeverity>>`, so a code added without a severity fails to compile.
+
+## Rules
+
+- No runtime dependency on any other `@sezzlee/*` package besides `@sezzlee/core`, which supplies
+  `CatalogSeverity` and the descriptor types this library fills in.
+- Bound by the `openapi-ingestion` fixture profile, not the core catalog's fixture profile — an
+  SDK that never reads an OpenAPI document is unaffected by a change here.
+
+## Development
+
+```bash
+pnpm turbo run build --filter=@sezzlee/openapi
+pnpm turbo run lint --filter=@sezzlee/openapi
+pnpm turbo run check-types --filter=@sezzlee/openapi
+pnpm turbo run test --filter=@sezzlee/openapi
+```
+
+Run these through Turbo rather than `pnpm --filter @sezzlee/openapi <task>`, per this repository's
+convention. `test/ingest.spec.ts` covers the pipeline directly; `test/conformance-fixtures.spec.ts`
+runs the package against the `openapi-ingestion` fixture corpus.

package/dist/diagnostics.d.ts

@@ -0,0 +1,61 @@
+import type { CatalogSeverity } from "@sezzlee/core";
+import type { JsonPointer } from "./ir/brand.js";
+export declare const ingestionSeverities: {
+    readonly openapi_document_unparseable: "fatal";
+    readonly openapi_version_unsupported: "fatal";
+    readonly openapi_document_invalid: "warning";
+    readonly external_ref_blocked: "fatal";
+    readonly server_variable_invalid: "fatal";
+    readonly server_url_unresolvable: "fatal";
+    readonly circular_component_ref: "endpointDropped";
+    readonly recursive_parameter_schema: "endpointDropped";
+    readonly unsupported_method: "endpointDropped";
+    readonly unsupported_collection_format: "endpointDropped";
+    readonly unsupported_parameter_content: "endpointDropped";
+    readonly unsupported_media_type: "endpointDropped";
+    readonly unsupported_encoding: "endpointDropped";
+    readonly streaming_response_unsupported: "endpointDropped";
+    readonly server_host_not_allowed: "endpointDropped";
+    readonly security_unsatisfiable: "endpointDropped";
+    readonly security_scheme_unsupported: "warning";
+    readonly ref_siblings_ignored: "warning";
+    readonly annotation_removed: "warning";
+    readonly reserved_header_parameter_ignored: "warning";
+    readonly credential_parameter_ignored: "warning";
+    readonly allow_empty_value_ignored: "warning";
+    readonly identity_cookie_parameter: "warning";
+    readonly identity_cookie_uncovered: "warning";
+    readonly request_media_type_alternative_ignored: "warning";
+    readonly operation_id_unusable: "warning";
+    readonly search_terms_invalid: "warning";
+    readonly callbacks_ignored: "warning";
+    readonly links_ignored: "warning";
+    readonly webhooks_ignored: "warning";
+};
+export type IngestionCode = keyof typeof ingestionSeverities;
+export interface IngestionDiagnostic {
+    readonly code: IngestionCode;
+    readonly severity: CatalogSeverity;
+    readonly at: JsonPointer;
+    readonly message: string;
+}
+/**
+ * Collects ingestion diagnostics.
+ *
+ * @param strict raises `openapi_document_invalid` to fatal
+ */
+export declare class DiagnosticSink {
+    private readonly strict;
+    private readonly entries;
+    private readonly reported;
+    constructor(strict?: boolean);
+    report(code: IngestionCode, at: JsonPointer, message: string): void;
+    get all(): readonly IngestionDiagnostic[];
+    get fatal(): boolean;
+}
+/** Raised inside one operation's lowering; the operation is dropped and the diagnostic reported. */
+export declare class OperationDropped extends Error {
+    readonly code: IngestionCode;
+    readonly at: JsonPointer;
+    constructor(code: IngestionCode, at: JsonPointer, message: string);
+}

package/dist/diagnostics.js

@@ -0,0 +1,82 @@
+export const ingestionSeverities = {
+    openapi_document_unparseable: "fatal",
+    openapi_version_unsupported: "fatal",
+    openapi_document_invalid: "warning",
+    external_ref_blocked: "fatal",
+    server_variable_invalid: "fatal",
+    server_url_unresolvable: "fatal",
+    circular_component_ref: "endpointDropped",
+    recursive_parameter_schema: "endpointDropped",
+    unsupported_method: "endpointDropped",
+    unsupported_collection_format: "endpointDropped",
+    unsupported_parameter_content: "endpointDropped",
+    unsupported_media_type: "endpointDropped",
+    unsupported_encoding: "endpointDropped",
+    streaming_response_unsupported: "endpointDropped",
+    server_host_not_allowed: "endpointDropped",
+    security_unsatisfiable: "endpointDropped",
+    security_scheme_unsupported: "warning",
+    ref_siblings_ignored: "warning",
+    annotation_removed: "warning",
+    reserved_header_parameter_ignored: "warning",
+    credential_parameter_ignored: "warning",
+    allow_empty_value_ignored: "warning",
+    identity_cookie_parameter: "warning",
+    identity_cookie_uncovered: "warning",
+    request_media_type_alternative_ignored: "warning",
+    operation_id_unusable: "warning",
+    search_terms_invalid: "warning",
+    callbacks_ignored: "warning",
+    links_ignored: "warning",
+    webhooks_ignored: "warning",
+};
+const oncePerDocument = new Set([
+    "annotation_removed",
+    "ref_siblings_ignored",
+    "callbacks_ignored",
+    "links_ignored",
+    "webhooks_ignored",
+]);
+/**
+ * Collects ingestion diagnostics.
+ *
+ * @param strict raises `openapi_document_invalid` to fatal
+ */
+export class DiagnosticSink {
+    strict;
+    entries = [];
+    reported = new Set();
+    constructor(strict = false) {
+        this.strict = strict;
+    }
+    report(code, at, message) {
+        if (oncePerDocument.has(code)) {
+            const key = `${code}|${message}`;
+            if (this.reported.has(key)) {
+                return;
+            }
+            this.reported.add(key);
+        }
+        const severity = this.strict && code === "openapi_document_invalid"
+            ? "fatal"
+            : ingestionSeverities[code];
+        this.entries.push({ code, severity, at, message });
+    }
+    get all() {
+        return this.entries;
+    }
+    get fatal() {
+        return this.entries.some((entry) => entry.severity === "fatal");
+    }
+}
+/** Raised inside one operation's lowering; the operation is dropped and the diagnostic reported. */
+export class OperationDropped extends Error {
+    code;
+    at;
+    constructor(code, at, message) {
+        super(message);
+        this.code = code;
+        this.at = at;
+        this.name = "OperationDropped";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { ingest } from "./ingest.js";
+export type { IngestOptions, IngestionResult } from "./ingest.js";
+export { ingestionSeverities } from "./diagnostics.js";
+export type { IngestionCode, IngestionDiagnostic } from "./diagnostics.js";
+export type { DocumentLoader } from "./normalize/external.js";
+export type { SourcedEndpoint } from "./lower/operations.js";
+export type { CredentialRef, SecurityModel, SecurityRequirement, SecurityScheme, } from "./lower/security.js";
+export type { HttpMethod, JsonPointer, OperationKey } from "./ir/brand.js";
+export type { JsonObject, JsonValue } from "./ir/json.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { ingest } from "./ingest.js";
+export { ingestionSeverities } from "./diagnostics.js";

package/dist/ingest.d.ts

@@ -0,0 +1,43 @@
+import { type IngestionDiagnostic } from "./diagnostics.js";
+import { type JsonObject } from "./ir/json.js";
+import { type DocumentLoader } from "./normalize/external.js";
+import { type SourcedEndpoint } from "./lower/operations.js";
+import { type SecurityModel } from "./lower/security.js";
+/**
+ * @param documentUrl where the document was read from; relative servers and external references
+ * resolve against it
+ * @param baseUrl replaces the document's root servers
+ * @param loader reads external references; without one, a document that has any is refused
+ * @param strict makes a document that fails validation fatal
+ * @param cookieDenyList cookie names treated as identity even when no security scheme declares them
+ * @param identityCookies further cookie names treated as identity, on top of the deny-list
+ * @param outputSchema `omit` for a backend whose responses do not match its document
+ * @param hoistPathPrefix a leading path segment moved from every route into the base URL
+ * @param requestBodyRequired `always` treats an undeclared `requestBody.required` as true, for a
+ * generator that omits it although the backend rejects an empty body
+ */
+export interface IngestOptions {
+    readonly documentUrl?: string;
+    readonly baseUrl?: string;
+    readonly serverVariables?: Readonly<Record<string, string>>;
+    readonly loader?: DocumentLoader;
+    readonly strict?: boolean;
+    readonly cookieDenyList?: RegExp;
+    readonly identityCookies?: readonly string[];
+    readonly outputSchema?: "document" | "omit";
+    readonly hoistPathPrefix?: string;
+    readonly requestBodyRequired?: "document" | "always";
+}
+export interface IngestionResult {
+    readonly endpoints: readonly SourcedEndpoint[];
+    /** The resolved root server, or the configured base URL that replaces it. */
+    readonly rootBaseUrl?: string;
+    readonly security: SecurityModel;
+    readonly diagnostics: readonly IngestionDiagnostic[];
+    readonly fatal: boolean;
+}
+/**
+ * Turns an OpenAPI document into catalog descriptors. It never throws for anything the document
+ * contains: every construct it cannot carry is a diagnostic. Only the loader's I/O can reject.
+ */
+export declare function ingest(source: string | JsonObject, options?: IngestOptions): Promise<IngestionResult>;

package/dist/ingest.js

@@ -0,0 +1,80 @@
+import { DiagnosticSink } from "./diagnostics.js";
+import { isObject } from "./ir/json.js";
+import { bundleExternal } from "./normalize/external.js";
+import { lowerOperations } from "./lower/operations.js";
+import { defaultCookieDenyList } from "./lower/parameters.js";
+import { securitySchemesOf } from "./lower/security.js";
+import { serverOf } from "./lower/servers.js";
+import { childPointer, rootPointer } from "./ir/brand.js";
+import { parseDocument, versionOf } from "./parse/parse.js";
+import { upgradeSwagger2 } from "./parse/swagger2.js";
+/**
+ * Turns an OpenAPI document into catalog descriptors. It never throws for anything the document
+ * contains: every construct it cannot carry is a diagnostic. Only the loader's I/O can reject.
+ */
+export async function ingest(source, options = {}) {
+    const diagnostics = new DiagnosticSink(options.strict ?? false);
+    const failed = () => ({
+        endpoints: [],
+        security: new Map(),
+        diagnostics: diagnostics.all,
+        fatal: true,
+    });
+    const parsed = typeof source === "string" ? parseDocument(source, diagnostics) : source;
+    if (parsed === undefined || !isObject(parsed)) {
+        return failed();
+    }
+    const version = versionOf(parsed, diagnostics);
+    if (version === undefined) {
+        return failed();
+    }
+    const upgraded = version === "2.0"
+        ? upgradeSwagger2(parsed, diagnostics, new WeakMap())
+        : parsed;
+    const document = await bundleExternal(upgraded, options.documentUrl, options.loader, diagnostics);
+    if (document === undefined || diagnostics.fatal) {
+        return failed();
+    }
+    const context = {
+        document,
+        version: version === "2.0" ? "3.0" : version,
+        diagnostics,
+    };
+    const security = securitySchemesOf(document, diagnostics);
+    const operationOptions = {
+        ...(options.documentUrl === undefined
+            ? {}
+            : { documentUrl: options.documentUrl }),
+        ...(options.baseUrl === undefined ? {} : { baseUrl: options.baseUrl }),
+        ...(options.serverVariables === undefined
+            ? {}
+            : { variables: options.serverVariables }),
+        cookieDenyList: withIdentityCookies(options.cookieDenyList ?? defaultCookieDenyList, options.identityCookies ?? []),
+        outputSchema: options.outputSchema ?? "document",
+        requestBodyRequired: options.requestBodyRequired ?? "document",
+        ...(options.hoistPathPrefix === undefined
+            ? {}
+            : { hoistPathPrefix: options.hoistPathPrefix }),
+    };
+    const endpoints = lowerOperations(context, security, operationOptions);
+    const rootBaseUrl = serverOf([], { servers: document["servers"], at: childPointer(rootPointer, "servers") }, operationOptions, new DiagnosticSink());
+    return {
+        endpoints: diagnostics.fatal ? [] : endpoints,
+        ...(rootBaseUrl === undefined ? {} : { rootBaseUrl }),
+        security,
+        diagnostics: diagnostics.all,
+        fatal: diagnostics.fatal,
+    };
+}
+/**
+ * Guard: the names extend the deny-list and never replace it. An operator adding
+ * the one session cookie their backend uses must not thereby switch off the
+ * default names that catch every other one.
+ */
+function withIdentityCookies(denyList, names) {
+    if (names.length === 0) {
+        return denyList;
+    }
+    const exact = names.map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    return new RegExp(`${denyList.source}|^(?:${exact.join("|")})$`, "i");
+}

package/dist/ir/brand.d.ts

@@ -0,0 +1,13 @@
+declare const brand: unique symbol;
+export type Brand<T, B extends string> = T & {
+    readonly [brand]: B;
+};
+/** An RFC 6901 pointer into the document as the author wrote it. */
+export type JsonPointer = Brand<string, "JsonPointer">;
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "QUERY" | "TRACE";
+export type OperationKey = Brand<`${HttpMethod} ${string}`, "OperationKey">;
+export declare const rootPointer: JsonPointer;
+export declare function childPointer(parent: JsonPointer, ...segments: readonly (string | number)[]): JsonPointer;
+export declare function segmentsOf(pointer: string): string[];
+export declare function operationKey(method: HttpMethod, path: string): OperationKey;
+export {};

package/dist/ir/brand.js

@@ -0,0 +1,18 @@
+export const rootPointer = "";
+const escapeSegment = (segment) => String(segment).replaceAll("~", "~0").replaceAll("/", "~1");
+export function childPointer(parent, ...segments) {
+    return `${parent}${segments.map((segment) => `/${escapeSegment(segment)}`).join("")}`;
+}
+export function segmentsOf(pointer) {
+    if (pointer === "" || pointer === "#") {
+        return [];
+    }
+    const body = pointer.startsWith("#") ? pointer.slice(1) : pointer;
+    return body
+        .split("/")
+        .slice(1)
+        .map((segment) => decodeURIComponent(segment).replaceAll("~1", "/").replaceAll("~0", "~"));
+}
+export function operationKey(method, path) {
+    return `${method} ${path}`;
+}

package/dist/ir/json.d.ts

@@ -0,0 +1,14 @@
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | JsonObject;
+export interface JsonObject {
+    readonly [key: string]: JsonValue | undefined;
+}
+export type MutableJsonObject = {
+    [key: string]: JsonValue | undefined;
+};
+export declare const isObject: (value: unknown) => value is JsonObject;
+export declare const objectOf: (value: unknown) => JsonObject | undefined;
+export declare const stringOf: (value: unknown) => string | undefined;
+export declare const booleanOf: (value: unknown) => boolean | undefined;
+export declare const arrayOf: (value: unknown) => readonly JsonValue[];
+export declare function entriesOf(value: unknown): ReadonlyArray<readonly [string, JsonValue]>;
+export declare function clone<T extends JsonValue>(value: T): T;

package/dist/ir/json.js

@@ -0,0 +1,14 @@
+export const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const objectOf = (value) => isObject(value) ? value : undefined;
+export const stringOf = (value) => typeof value === "string" ? value : undefined;
+export const booleanOf = (value) => typeof value === "boolean" ? value : undefined;
+export const arrayOf = (value) => Array.isArray(value) ? value : [];
+export function entriesOf(value) {
+    if (!isObject(value)) {
+        return [];
+    }
+    return Object.entries(value).filter((entry) => entry[1] !== undefined);
+}
+export function clone(value) {
+    return structuredClone(value);
+}

package/dist/lower/body.d.ts

@@ -0,0 +1,6 @@
+import { type EndpointDescriptor } from "@sezzlee/core";
+import { type JsonPointer } from "../ir/brand.js";
+import { type SchemaContext } from "../normalize/schema.js";
+type RequestBody = NonNullable<EndpointDescriptor["requestBody"]>;
+export declare function lowerRequestBody(context: SchemaContext, value: unknown, at: JsonPointer, requiredDefault?: "document" | "always"): RequestBody | undefined;
+export {};

package/dist/lower/body.js

@@ -0,0 +1,127 @@
+import { isBinaryMediaType, isJsonMediaType, jsonMediaType, multipartMediaType, textMediaType, urlEncodedMediaType, } from "@sezzlee/core";
+import { OperationDropped } from "../diagnostics.js";
+import { childPointer } from "../ir/brand.js";
+import { entriesOf, isObject, objectOf, stringOf, } from "../ir/json.js";
+import { resolveComponent } from "../normalize/refs.js";
+import { normalizeSlot } from "../normalize/schema.js";
+const bareMediaType = (declared) => (declared.split(";")[0] ?? "").trim().toLowerCase();
+const isFileRoot = (schema) => schema.contentMediaType !== undefined && schema.contentEncoding === undefined;
+const hasFileField = (schema) => Object.values(schema.properties ?? {}).some((property) => (property.contentMediaType !== undefined &&
+    property.contentEncoding === undefined) ||
+    (property.items?.contentMediaType !== undefined &&
+        property.items.contentEncoding === undefined));
+/**
+ * Picks the one media type the body is written as, in the order of request-bodies.md: JSON (also
+ * when a wildcard covers it), another JSON-family type in declared order, urlencoded when no field
+ * is a file, multipart, text/plain.
+ */
+function choose(candidates, schemaOf) {
+    const exact = candidates.find((candidate) => candidate.mediaType === jsonMediaType);
+    if (exact !== undefined) {
+        return exact;
+    }
+    const wildcard = candidates.find((candidate) => candidate.mediaType === "*/*" || candidate.mediaType === "application/*");
+    if (wildcard !== undefined) {
+        return { ...wildcard, mediaType: jsonMediaType };
+    }
+    const family = candidates.find((candidate) => isJsonMediaType(candidate.mediaType));
+    if (family !== undefined) {
+        return family;
+    }
+    const urlencoded = candidates.find((candidate) => candidate.mediaType === urlEncodedMediaType);
+    if (urlencoded !== undefined && !hasFileField(schemaOf(urlencoded))) {
+        return urlencoded;
+    }
+    return (candidates.find((candidate) => candidate.mediaType === multipartMediaType) ??
+        candidates.find((candidate) => candidate.mediaType === textMediaType) ??
+        candidates.find((candidate) => candidate.mediaType === "application/octet-stream" &&
+            isFileRoot(schemaOf(candidate))) ??
+        candidates.find((candidate) => isBinaryMediaType(candidate.mediaType) &&
+            !candidate.mediaType.includes("*") &&
+            isFileRoot(schemaOf(candidate))));
+}
+function assertEncoding(media, at) {
+    for (const [field, raw] of entriesOf(media["encoding"])) {
+        const encoding = objectOf(raw);
+        const style = stringOf(encoding?.["style"]);
+        const unsupported = (style !== undefined && style !== "form") ||
+            encoding?.["explode"] === false ||
+            encoding?.["allowReserved"] === true ||
+            objectOf(encoding?.["headers"]) !== undefined;
+        if (unsupported) {
+            throw new OperationDropped("unsupported_encoding", childPointer(at, "encoding", field), `The encoding of '${field}' declares a style, explode, allowReserved or part headers the form writers do not produce.`);
+        }
+    }
+}
+/**
+ * A body whose root admits `null` is a body the backend accepts absent: `null` is not a JSON body
+ * a client sends, it is how a generator writes an optional parameter's type (`NotePayload?`). The
+ * null member is removed so the root can flatten, and the body is optional unless the document
+ * declares it required.
+ */
+function withoutNullRoot(schema) {
+    const type = schema.type;
+    if (Array.isArray(type) && type.includes("null")) {
+        const rest = type.filter((member) => member !== "null");
+        return {
+            schema: {
+                ...schema,
+                type: rest.length === 1 ? rest[0] : rest,
+            },
+            nullable: true,
+        };
+    }
+    return { schema, nullable: false };
+}
+export function lowerRequestBody(context, value, at, requiredDefault = "document") {
+    if (value === undefined) {
+        return undefined;
+    }
+    const resolved = resolveComponent(context.document, isObject(value) ? value : {}, at);
+    if (resolved === undefined) {
+        return undefined;
+    }
+    const { node, at: bodyAt } = resolved;
+    const contentAt = childPointer(bodyAt, "content");
+    const candidates = entriesOf(node["content"]).flatMap(([declared, media]) => isObject(media)
+        ? [{ declared, mediaType: bareMediaType(declared), media }]
+        : []);
+    const schemaOf = (candidate) => {
+        const mediaAt = childPointer(contentAt, candidate.declared);
+        const encoding = objectOf(candidate.media["encoding"]);
+        return normalizeSlot(context, candidate.media["schema"], childPointer(mediaAt, "schema"), {
+            direction: "request",
+            root: "preferred",
+            fileMediaType: (property) => stringOf(objectOf(encoding?.[property])?.["contentType"])
+                ?.split(",")[0]
+                ?.trim(),
+        });
+    };
+    const chosen = choose(candidates, schemaOf);
+    if (chosen === undefined) {
+        throw new OperationDropped("unsupported_media_type", contentAt, `No declared body media type has a writer: ${candidates.map((candidate) => candidate.declared).join(", ") || "none declared"}.`);
+    }
+    for (const candidate of candidates) {
+        if (candidate.declared !== chosen.declared) {
+            context.diagnostics.report("request_media_type_alternative_ignored", childPointer(contentAt, candidate.declared), `The body is written as ${chosen.mediaType}; the alternative ${candidate.declared} is not used.`);
+        }
+    }
+    assertEncoding(chosen.media, childPointer(contentAt, chosen.declared));
+    const description = stringOf(node["description"]);
+    const { schema: normalized, nullable } = withoutNullRoot(schemaOf(chosen));
+    const schema = isBinaryMediaType(chosen.mediaType) && isFileRoot(normalized)
+        ? { ...normalized, contentMediaType: chosen.mediaType }
+        : normalized;
+    const required = node["required"] === true ||
+        (node["required"] === undefined &&
+            requiredDefault === "always" &&
+            !nullable);
+    return {
+        schema,
+        ...(required ? {} : { required: false }),
+        ...(description === undefined ? {} : { description }),
+        ...(chosen.mediaType === jsonMediaType
+            ? {}
+            : { contentType: chosen.mediaType }),
+    };
+}

package/dist/lower/operations.d.ts

@@ -0,0 +1,20 @@
+import { type EndpointDescriptor } from "@sezzlee/core";
+import { type JsonPointer, type OperationKey } from "../ir/brand.js";
+import type { SchemaContext } from "../normalize/schema.js";
+import { type SecurityModel, type SecurityRequirement } from "./security.js";
+import { type ServerOptions } from "./servers.js";
+export interface SourcedEndpoint {
+    readonly key: OperationKey;
+    readonly at: JsonPointer;
+    readonly descriptor: EndpointDescriptor;
+    /** The base URL the route is appended to, with any hoisted prefix; `undefined` when unresolvable. */
+    readonly baseUrl: string | undefined;
+    readonly security: readonly SecurityRequirement[] | undefined;
+}
+export interface OperationOptions extends ServerOptions {
+    readonly cookieDenyList: RegExp;
+    readonly outputSchema: "document" | "omit";
+    readonly requestBodyRequired: "document" | "always";
+    readonly hoistPathPrefix?: string;
+}
+export declare function lowerOperations(context: SchemaContext, schemes: SecurityModel, options: OperationOptions): SourcedEndpoint[];