@haddowg/json-api-codegen 1.6.1 → 1.7.0

package/dist/cli.d.mts

@@ -1,4 +1,4 @@
-import { r as CodegenConfig } from "./index-CjNGhJJH.mjs";
+import { r as CodegenConfig } from "./index-CeSU_OuC.mjs";
 
 //#region src/cli.d.ts
 declare const USAGE = "Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--check]";

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as generate, r as schemasOutputPath, t as check } from "./src-CKsM7dXw.mjs";
+import { n as generate, r as schemasOutputPath, t as check } from "./src-DhZyiWge.mjs";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/cli.ts

package/dist/{index-CjNGhJJH.d.mts → index-CeSU_OuC.d.mts}

@@ -49,6 +49,8 @@ interface ParameterObject {
 }
 interface OperationObject {
   operationId?: string;
+  summary?: string;
+  description?: string;
   parameters?: readonly ParameterObject[];
   requestBody?: RequestBodyObject;
   responses?: Record<string, ResponseObject>;
@@ -151,6 +153,21 @@ declare class DescriptorBuilder {
    * `output` is `document` (a 2xx returns a JSON:API document) or `none` (only `204`).
    */
   private actions;
+  /**
+   * The non-JSON:API media types an action answers with under its 2xx responses, each once, in
+   * the document's order, with how the client reads its body.
+   */
+  private rawOutput;
+  /**
+   * How the client reads or sends a non-JSON:API body: `binary` for `format: binary` (or no schema
+   * on a type that isn't text or JSON), `text` for any other string schema (or no schema on a
+   * `text/*` type), `json` for any other schema (or no schema on a JSON type).
+   */
+  private rawMediaKind;
+  /** How the client sends one of an action's several request media types. */
+  private inputMediaKind;
+  /** A schema with a component `$ref` followed, else the schema as is. */
+  private resolveSchema;
   /**
    * The wire type (and cardinality) of a document component's primary `data` — a `$ref` to a
    * resource, an inline object carrying `properties.type.const` (a create-request body), or an
@@ -260,7 +277,7 @@ declare function buildAtomic(doc: OpenApiDocument): AtomicDescriptor | null;
 /** Below this the document predates the structures this codegen reads. */
 declare const MINIMUM_CONTRACT = 1;
 /** Above this the document carries structures this codegen does not read. */
-declare const MAXIMUM_CONTRACT = 9;
+declare const MAXIMUM_CONTRACT = 11;
 /**
  * Check the document's `info.x-generator.contract` against the range this codegen reads. A
  * document older than the range throws; a newer one returns a warning, because its new
@@ -307,10 +324,16 @@ declare class Emitter {
    * type-map only references aliases that exist (a `none` input/output contributes neither).
    */
   private readonly actionAliasNames;
+  /** Raw body components already emitted as a named alias, by component name. */
+  private readonly rawBodyAliases;
+  /** JSDoc for entries of the `resourceMap` literal, keyed by their path joined with `/`. */
+  private readonly literalDocs;
   /** Provenance of the source document, stamped into the generated header for drift tracking. */
   private readonly provenance;
   private readonly doc;
   constructor(source: OpenApiDocument, descriptor: ApiDescriptor, atomic: AtomicDescriptor | null);
+  /** The operation an action is invoked over: its declared method, else `POST`. */
+  private actionOperation;
   /**
    * The alias an enum component is emitted under: its own name when that's a usable type name,
    * else one derived from it (with a warning), kept clear of every other name in the module.
@@ -339,6 +362,26 @@ declare class Emitter {
    * no alias. Deterministic order: types, then action names (the descriptor is sorted).
    */
   private actionTypeAliases;
+  /**
+   * The alias a JSON-like raw body is typed by. A `$ref` to a component is emitted once under the
+   * component's own name when that name is free; anything else gets `fallback`. The alias source
+   * is pushed onto `out` the first time.
+   */
+  private rawBodyAlias;
+  /**
+   * The typed fields of a multipart or URL-encoded request body whose object schema lists
+   * `properties`, which the client encodes into a `FormData` or `URLSearchParams`. `undefined`
+   * when the schema lists none, so the body stays a raw `FormData` or `URLSearchParams`.
+   */
+  private formFieldsType;
+  /**
+   * One form field's type: `Blob | File` for a binary part of a multipart body, an array of
+   * its item type for an array, else the scalar's own type. A field with no usable type takes
+   * any scalar a form can carry.
+   */
+  private formFieldType;
+  /** `export type Name = …` for a raw body schema, with its description as JSDoc. */
+  private rawBodyDeclaration;
   /**
    * Emit the `ActionTypes` interface wiring the emitted per-action aliases onto the typed
    * action surface — `type -> actionName -> { input?; output? }`, the client's fourth type
@@ -574,4 +617,4 @@ declare function generate(config: CodegenConfig): Promise<string>;
 declare function check(config: CodegenConfig): Promise<CheckResult>;
 //#endregion
 export { InfoObject as A, MAXIMUM_CONTRACT as C, buildAtomic as D, DescriptorBuilder as E, PathItemObject as F, RequestBodyObject as I, ResponseObject as L, OpenApiDocument as M, OperationObject as N, buildDescriptor as O, ParameterObject as P, SchemaObject as R, emit as S, checkContract as T, emitErrorCodes as _, generate as a, VerbCollision as b, deriveProvenance as c, emitSchemas as d, SchemaBundle as f, ErrorCatalogue as g, DocumentedErrorCode as h, check as i, MediaTypeObject as j, HttpMethod as k, hashJson as l, readSchemas as m, CheckResult as n, schemasOutputPath as o, readDocument as p, CodegenConfig as r, Provenance as s, ArtifactDrift as t, provenanceLines as u, readErrorCatalogue as v, MINIMUM_CONTRACT as w, detectVerbCollisions as x, Emitter as y, SchemaOrBool as z };
-//# sourceMappingURL=index-CjNGhJJH.d.mts.map
+//# sourceMappingURL=index-CeSU_OuC.d.mts.map

package/dist/index-CeSU_OuC.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CeSU_OuC.d.mts","names":[],"sources":["../src/openapi.ts","../src/build-descriptor.ts","../src/contract.ts","../src/emit.ts","../src/error-codes.ts","../src/reader.ts","../src/emit-schemas.ts","../src/provenance.ts","../src/index.ts"],"mappings":"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"}

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { A as InfoObject, C as MAXIMUM_CONTRACT, D as buildAtomic, E as DescriptorBuilder, F as PathItemObject, I as RequestBodyObject, L as ResponseObject, M as OpenApiDocument, N as OperationObject, O as buildDescriptor, P as ParameterObject, R as SchemaObject, S as emit, T as checkContract, _ as emitErrorCodes, a as generate, b as VerbCollision, c as deriveProvenance, d as emitSchemas, f as SchemaBundle, g as ErrorCatalogue, h as DocumentedErrorCode, i as check, j as MediaTypeObject, k as HttpMethod, l as hashJson, m as readSchemas, n as CheckResult, o as schemasOutputPath, p as readDocument, r as CodegenConfig, s as Provenance, t as ArtifactDrift, u as provenanceLines, v as readErrorCatalogue, w as MINIMUM_CONTRACT, x as detectVerbCollisions, y as Emitter, z as SchemaOrBool } from "./index-CjNGhJJH.mjs";
+import { A as InfoObject, C as MAXIMUM_CONTRACT, D as buildAtomic, E as DescriptorBuilder, F as PathItemObject, I as RequestBodyObject, L as ResponseObject, M as OpenApiDocument, N as OperationObject, O as buildDescriptor, P as ParameterObject, R as SchemaObject, S as emit, T as checkContract, _ as emitErrorCodes, a as generate, b as VerbCollision, c as deriveProvenance, d as emitSchemas, f as SchemaBundle, g as ErrorCatalogue, h as DocumentedErrorCode, i as check, j as MediaTypeObject, k as HttpMethod, l as hashJson, m as readSchemas, n as CheckResult, o as schemasOutputPath, p as readDocument, r as CodegenConfig, s as Provenance, t as ArtifactDrift, u as provenanceLines, v as readErrorCatalogue, w as MINIMUM_CONTRACT, x as detectVerbCollisions, y as Emitter, z as SchemaOrBool } from "./index-CeSU_OuC.mjs";
 export { ArtifactDrift, CheckResult, CodegenConfig, DescriptorBuilder, type DocumentedErrorCode, Emitter, type ErrorCatalogue, type HttpMethod, type InfoObject, MAXIMUM_CONTRACT, MINIMUM_CONTRACT, type MediaTypeObject, type OpenApiDocument, type OperationObject, type ParameterObject, type PathItemObject, type Provenance, type RequestBodyObject, type ResponseObject, type SchemaBundle, type SchemaObject, type SchemaOrBool, type VerbCollision, buildAtomic, buildDescriptor, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitSchemas, generate, hashJson, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { _ as checkContract, a as readSchemas, b as buildDescriptor, c as detectVerbCollisions, d as hashJson, f as provenanceLines, g as MINIMUM_CONTRACT, h as MAXIMUM_CONTRACT, i as readDocument, l as emit, m as readErrorCatalogue, n as generate, o as emitSchemas, p as emitErrorCodes, r as schemasOutputPath, s as Emitter, t as check, u as deriveProvenance, v as DescriptorBuilder, y as buildAtomic } from "./src-CKsM7dXw.mjs";
+import { _ as checkContract, a as readSchemas, b as buildDescriptor, c as detectVerbCollisions, d as hashJson, f as provenanceLines, g as MINIMUM_CONTRACT, h as MAXIMUM_CONTRACT, i as readDocument, l as emit, m as readErrorCatalogue, n as generate, o as emitSchemas, p as emitErrorCodes, r as schemasOutputPath, s as Emitter, t as check, u as deriveProvenance, v as DescriptorBuilder, y as buildAtomic } from "./src-DhZyiWge.mjs";
 export { DescriptorBuilder, Emitter, MAXIMUM_CONTRACT, MINIMUM_CONTRACT, buildAtomic, buildDescriptor, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitSchemas, generate, hashJson, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };

package/dist/{src-CKsM7dXw.mjs → src-DhZyiWge.mjs}

@@ -374,11 +374,63 @@ var DescriptorBuilder = class {
 				const contentType = rawContentType(op);
 				if (contentType !== void 0) action.contentType = contentType;
 			}
+			const rawOutput = this.rawOutput(op);
+			if (rawOutput.length > 0) action.rawOutput = rawOutput;
+			const requestContent = Object.entries(op.requestBody?.content ?? {});
+			if (requestContent.length > 1) action.inputMedia = requestContent.map(([mediaType, media]) => ({
+				mediaType,
+				kind: this.inputMediaKind(mediaType, media.schema)
+			}));
 			out[name] = action;
 		}
 		return sortRecord(out);
 	}
 	/**
+	* The non-JSON:API media types an action answers with under its 2xx responses, each once, in
+	* the document's order, with how the client reads its body.
+	*/
+	rawOutput(op) {
+		const out = [];
+		for (const [code, response] of Object.entries(op.responses ?? {})) {
+			if (!code.startsWith("2")) continue;
+			for (const [mediaType, media] of Object.entries(response.content ?? {})) {
+				if (isJsonApiMediaType(mediaType) || out.some((entry) => entry.mediaType === mediaType)) continue;
+				out.push({
+					mediaType,
+					kind: this.rawMediaKind(mediaType, media.schema)
+				});
+			}
+		}
+		return out;
+	}
+	/**
+	* How the client reads or sends a non-JSON:API body: `binary` for `format: binary` (or no schema
+	* on a type that isn't text or JSON), `text` for any other string schema (or no schema on a
+	* `text/*` type), `json` for any other schema (or no schema on a JSON type).
+	*/
+	rawMediaKind(mediaType, schema) {
+		const resolved = this.resolveSchema(schema);
+		if (resolved === void 0) {
+			if (mediaType.startsWith("text/")) return "text";
+			return isJsonMediaType(mediaType) ? "json" : "binary";
+		}
+		if (resolved.type === "string") return resolved.format === "binary" ? "binary" : "text";
+		return "json";
+	}
+	/** How the client sends one of an action's several request media types. */
+	inputMediaKind(mediaType, schema) {
+		if (isJsonApiMediaType(mediaType)) return "document";
+		if (mediaType.startsWith("multipart/")) return "multipart";
+		if (mediaType === "application/x-www-form-urlencoded") return "form";
+		return this.rawMediaKind(mediaType, schema);
+	}
+	/** A schema with a component `$ref` followed, else the schema as is. */
+	resolveSchema(schema) {
+		if (schema === void 0 || typeof schema.$ref !== "string") return schema;
+		const name = refName$1(schema.$ref);
+		return name === void 0 ? schema : this.schemas[name] ?? schema;
+	}
+	/**
 	* The wire type (and cardinality) of a document component's primary `data` — a `$ref` to a
 	* resource, an inline object carrying `properties.type.const` (a create-request body), or an
 	* array of resource/identifier refs (a collection). `undefined` when the type can't be resolved.
@@ -767,6 +819,15 @@ function paramItemsEnum(op, paramName) {
 function isAtomicMediaType(mediaType) {
 	return mediaType.startsWith(JSON_API_MEDIA_TYPE$1) && mediaType.includes(ATOMIC_EXT);
 }
+/** Whether a media type is JSON:API, with or without `ext` / `profile` parameters. */
+function isJsonApiMediaType(mediaType) {
+	return mediaType.split(";")[0].trim().toLowerCase() === JSON_API_MEDIA_TYPE$1;
+}
+/** Whether a non-JSON:API media type carries JSON: `application/json` or a `+json` suffix. */
+function isJsonMediaType(mediaType) {
+	const essence = mediaType.split(";")[0].trim().toLowerCase();
+	return essence === "application/json" || essence.endsWith("+json");
+}
 /** The HTTP methods an action operation may be advertised under, in resolution preference order. */
 const ACTION_METHODS = [
 	"post",
@@ -905,7 +966,7 @@ function stampedMenu(schema, stamp, warn) {
 /** Below this the document predates the structures this codegen reads. */
 const MINIMUM_CONTRACT = 1;
 /** Above this the document carries structures this codegen does not read. */
-const MAXIMUM_CONTRACT = 9;
+const MAXIMUM_CONTRACT = 11;
 /**
 * Check the document's `info.x-generator.contract` against the range this codegen reads. A
 * document older than the range throws; a newer one returns a warning, because its new
@@ -915,8 +976,8 @@ const MAXIMUM_CONTRACT = 9;
 function checkContract(doc) {
 	const contract = doc.info?.["x-generator"]?.contract;
 	if (typeof contract !== "number") return;
-	if (contract < 1) throw new Error(`the document declares contract ${contract}, which predates what this codegen reads (it supports 1 to 9). Use an older codegen release, or regenerate the document from a newer server.`);
-	if (contract > 9) return `the document declares contract ${contract} and this codegen reads up to 9. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
+	if (contract < 1) throw new Error(`the document declares contract ${contract}, which predates what this codegen reads (it supports 1 to 11). Use an older codegen release, or regenerate the document from a newer server.`);
+	if (contract > 11) return `the document declares contract ${contract} and this codegen reads up to 11. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
 }
 //#endregion
 //#region src/source.ts
@@ -1318,6 +1379,34 @@ function memberDoc(schema) {
 	if (tags.length === 0) return description;
 	return description ? `${description}\n\n${tags.join("\n")}` : tags.join("\n");
 }
+/** An `ActionTypes` media map: `{ 'text/csv': Alias; … }`. */
+function mediaMap(aliases) {
+	return `{ ${[...aliases].map(([mediaType, alias]) => `${stringLiteral(mediaType)}: ${alias}`).join("; ")} }`;
+}
+/** The schema of `mediaType` under an operation's first 2xx response that lists it. */
+function firstSuccessSchema(op, mediaType) {
+	for (const [code, response] of Object.entries(op?.responses ?? {})) {
+		const media = code.startsWith("2") ? response.content?.[mediaType] : void 0;
+		if (media !== void 0) return media.schema;
+	}
+}
+/**
+* An action's summary and description as JSDoc, leaving out the prose the projector writes for an
+* action whose author gave none ("Invoke the `name` action", "Invokes the `name` custom action on
+* …"), which says nothing the name doesn't.
+*/
+function actionDoc(name, op) {
+	const summary = op?.summary?.trim();
+	const description = op?.description?.trim();
+	const parts = [];
+	if (summary && summary !== `Invoke the \`${name}\` action`) parts.push(summary);
+	const generated = new RegExp(`^Invokes the \`${escapeRegExp(name)}\` custom action on [^.]*\\.$`);
+	if (description && !generated.test(description)) parts.push(description);
+	return parts.length === 0 ? void 0 : parts.join("\n\n");
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 var Emitter = class {
 	descriptor;
 	atomic;
@@ -1345,6 +1434,10 @@ var Emitter = class {
 	* type-map only references aliases that exist (a `none` input/output contributes neither).
 	*/
 	actionAliasNames = /* @__PURE__ */ new Map();
+	/** Raw body components already emitted as a named alias, by component name. */
+	rawBodyAliases = /* @__PURE__ */ new Map();
+	/** JSDoc for entries of the `resourceMap` literal, keyed by their path joined with `/`. */
+	literalDocs = /* @__PURE__ */ new Map();
 	/** Provenance of the source document, stamped into the generated header for drift tracking. */
 	provenance;
 	doc;
@@ -1363,12 +1456,23 @@ var Emitter = class {
 				"CreateAttributes",
 				"UpdateAttributes"
 			]) this.takenNames.add(`${stem}${suffix}`);
-			for (const action of Object.keys(descriptor[type]?.actions ?? {})) {
-				this.takenNames.add(`${stem}${pascalCase(action)}Input`);
-				this.takenNames.add(`${stem}${pascalCase(action)}Output`);
+			for (const [name, action] of Object.entries(descriptor[type]?.actions ?? {})) {
+				this.takenNames.add(`${stem}${pascalCase(name)}Input`);
+				this.takenNames.add(`${stem}${pascalCase(name)}Output`);
+				for (const { mediaType } of action.rawOutput ?? []) this.takenNames.add(`${stem}${pascalCase(name)}${pascalCase(mediaType)}Output`);
+				for (const { mediaType } of action.inputMedia ?? []) this.takenNames.add(`${stem}${pascalCase(name)}${pascalCase(mediaType)}Input`);
+				const single = action.contentType;
+				if (single !== void 0 && (single.startsWith("multipart/") || single === "application/x-www-form-urlencoded")) this.takenNames.add(`${stem}${pascalCase(name)}${pascalCase(single)}Input`);
+				const doc = actionDoc(name, this.actionOperation(action));
+				if (doc !== void 0) this.literalDocs.set(`${type}/actions/${name}`, doc);
 			}
 		}
 	}
+	/** The operation an action is invoked over: its declared method, else `POST`. */
+	actionOperation(action) {
+		const method = (action.method ?? "POST").toLowerCase();
+		return this.doc.paths?.[action.path]?.[method];
+	}
 	/**
 	* The alias an enum component is emitted under: its own name when that's a usable type name,
 	* else one derived from it (with a warning), kept clear of every other name in the module.
@@ -1501,7 +1605,35 @@ var Emitter = class {
 					out.push(`export type ${member}Output = ${outputType}`);
 					names.output = `${member}Output`;
 				}
-				if (names.input !== void 0 || names.output !== void 0) {
+				const op = this.actionOperation(action);
+				for (const { mediaType, kind } of action.rawOutput ?? []) if (kind === "json") {
+					const schema = firstSuccessSchema(op, mediaType);
+					names.responses ??= /* @__PURE__ */ new Map();
+					names.responses.set(mediaType, this.rawBodyAlias(schema, `${member}${pascalCase(mediaType)}Output`, out));
+				}
+				const singleKind = !(action.input === "raw" && action.inputMedia === void 0) ? void 0 : action.contentType?.startsWith("multipart/") === true ? "multipart" : action.contentType === "application/x-www-form-urlencoded" ? "form" : void 0;
+				const listed = action.inputMedia ?? (singleKind === void 0 || action.contentType === void 0 ? [] : [{
+					mediaType: action.contentType,
+					kind: singleKind
+				}]);
+				for (const { mediaType, kind } of listed) {
+					const schema = op?.requestBody?.content?.[mediaType]?.schema;
+					if (kind === "json") {
+						names.requests ??= /* @__PURE__ */ new Map();
+						names.requests.set(mediaType, this.rawBodyAlias(schema, `${member}${pascalCase(mediaType)}Input`, out));
+					} else if (kind === "multipart" || kind === "form") {
+						const fields = this.formFieldsType(schema, kind);
+						if (fields !== void 0) {
+							const alias = `${member}${pascalCase(mediaType)}Input`;
+							const doc = schema === void 0 ? void 0 : jsDoc(schema.description, "");
+							const declaration = `export type ${alias} = ${fields}`;
+							out.push(doc === void 0 ? declaration : `${doc}\n${declaration}`);
+							names.requests ??= /* @__PURE__ */ new Map();
+							names.requests.set(mediaType, alias);
+						}
+					}
+				}
+				if (names.input !== void 0 || names.output !== void 0 || names.responses !== void 0 || names.requests !== void 0) {
 					let byAction = this.actionAliasNames.get(type);
 					if (byAction === void 0) {
 						byAction = /* @__PURE__ */ new Map();
@@ -1514,6 +1646,83 @@ var Emitter = class {
 		return out;
 	}
 	/**
+	* The alias a JSON-like raw body is typed by. A `$ref` to a component is emitted once under the
+	* component's own name when that name is free; anything else gets `fallback`. The alias source
+	* is pushed onto `out` the first time.
+	*/
+	rawBodyAlias(schema, fallback, out) {
+		const target = typeof schema?.$ref === "string" ? refName(schema.$ref) : void 0;
+		const resolved = target === void 0 ? void 0 : this.schemas[target];
+		if (target !== void 0 && resolved !== void 0) {
+			const known = this.rawBodyAliases.get(target);
+			if (known !== void 0) return known;
+			if (isTypeName(target) && !this.takenNames.has(target) && !Array.isArray(resolved.enum)) {
+				this.takenNames.add(target);
+				this.rawBodyAliases.set(target, target);
+				out.push(this.rawBodyDeclaration(target, resolved));
+				this.emittedInterfaces.add(target);
+				return target;
+			}
+		}
+		out.push(this.rawBodyDeclaration(fallback, schema));
+		return fallback;
+	}
+	/**
+	* The typed fields of a multipart or URL-encoded request body whose object schema lists
+	* `properties`, which the client encodes into a `FormData` or `URLSearchParams`. `undefined`
+	* when the schema lists none, so the body stays a raw `FormData` or `URLSearchParams`.
+	*/
+	formFieldsType(schema, kind) {
+		let target = schema;
+		if (typeof target?.$ref === "string") target = this.schemas[refName(target.$ref) ?? ""];
+		const props = target?.properties;
+		if (target === void 0 || props === void 0) return;
+		const required = new Set(target.required ?? []);
+		const members = [];
+		const valueTypes = [];
+		for (const [name, prop] of Object.entries(props)) {
+			if (!isSchema(prop)) continue;
+			const type = this.formFieldType(prop, kind);
+			valueTypes.push(type);
+			members.push(`${propertyKey(name)}${required.has(name) ? "" : "?"}: ${type}`);
+		}
+		if (members.length === 0) return;
+		const extra = target["additionalProperties"];
+		if (extra === true || isSchema(extra)) {
+			const additional = isSchema(extra) ? this.formFieldType(extra, kind) : this.formFieldType({}, kind);
+			const all = [...new Set([...valueTypes, additional].flatMap((type) => type.split(" | ")))];
+			members.push(`[field: string]: ${all.join(" | ")} | undefined`);
+		}
+		return `{ ${members.join("; ")} }`;
+	}
+	/**
+	* One form field's type: `Blob | File` for a binary part of a multipart body, an array of
+	* its item type for an array, else the scalar's own type. A field with no usable type takes
+	* any scalar a form can carry.
+	*/
+	formFieldType(schema, kind) {
+		const any = kind === "multipart" ? "string | number | boolean | Blob" : "string | number | boolean";
+		let target = schema;
+		if (typeof target.$ref === "string") {
+			const resolved = this.schemas[refName(target.$ref) ?? ""];
+			if (resolved !== void 0 && !Array.isArray(resolved.enum)) target = resolved;
+		}
+		if (kind === "multipart" && target.format === "binary") return "Blob | File";
+		if (target.type === "array") {
+			const item = target.items === void 0 ? any : this.formFieldType(target.items, kind);
+			return item.includes(" ") ? `(${item})[]` : `${item}[]`;
+		}
+		const type = this.tsType(target);
+		return type === "unknown" || type.includes("{") || type.startsWith("Record<") ? any : type;
+	}
+	/** `export type Name = …` for a raw body schema, with its description as JSDoc. */
+	rawBodyDeclaration(name, schema) {
+		const type = schema === void 0 ? "unknown" : this.tsType(schema);
+		const doc = schema === void 0 ? void 0 : jsDoc(schema.description, "");
+		const declaration = `export type ${name} = ${type}`;
+		return doc === void 0 ? declaration : `${doc}\n${declaration}`;
+	}
+	/**
 	* Emit the `ActionTypes` interface wiring the emitted per-action aliases onto the typed
 	* action surface — `type -> actionName -> { input?; output? }`, the client's fourth type
 	* argument. So `client.albums.id(id).actions.reissue(body)` takes `AlbumsReissueInput` and
@@ -1531,6 +1740,8 @@ var Emitter = class {
 				const members = [];
 				if (names.input !== void 0) members.push(`input: ${names.input}`);
 				if (names.output !== void 0) members.push(`output: ${names.output}`);
+				if (names.responses !== void 0) members.push(`responses: ${mediaMap(names.responses)}`);
+				if (names.requests !== void 0) members.push(`requests: ${mediaMap(names.requests)}`);
 				actionLines.push(`    ${propertyKey(actionName)}: { ${members.join("; ")} }`);
 			}
 			typeLines.push(`  ${propertyKey(type)}: {\n${actionLines.join("\n")}\n  }`);
@@ -1756,10 +1967,10 @@ var Emitter = class {
 	}
 	/** Emit the descriptor as a literal `as const satisfies ApiDescriptor`. */
 	resourceMap() {
-		return `export const resourceMap = ${this.literal(this.descriptor, 0)} as const satisfies ApiDescriptor`;
+		return `export const resourceMap = ${this.literal(this.descriptor, 0, "")} as const satisfies ApiDescriptor`;
 	}
 	/** Render a JSON-serialisable descriptor value as deterministic TS object-literal source. */
-	literal(value, depth) {
+	literal(value, depth, path) {
 		const indent = "  ".repeat(depth);
 		const inner = "  ".repeat(depth + 1);
 		if (Array.isArray(value)) {
@@ -1769,7 +1980,12 @@ var Emitter = class {
 		if (value !== null && typeof value === "object") {
 			const entries = Object.entries(value);
 			if (entries.length === 0) return "{}";
-			return `{\n${entries.map(([key, v]) => `${inner}${propertyKey(key)}: ${this.literal(v, depth + 1)}`).join(",\n")}\n${indent}}`;
+			return `{\n${entries.map(([key, v]) => {
+				const childPath = path === void 0 ? void 0 : path === "" ? key : `${path}/${key}`;
+				const line = `${inner}${propertyKey(key)}: ${this.literal(v, depth + 1, childPath)}`;
+				const doc = childPath === void 0 ? void 0 : this.literalDocs.get(childPath);
+				return doc === void 0 ? line : `${jsDoc(doc, inner)}\n${line}`;
+			}).join(",\n")}\n${indent}}`;
 		}
 		return typeof value === "string" ? stringLiteral(value) : JSON.stringify(value);
 	}
@@ -1974,4 +2190,4 @@ async function check(config) {
 //#endregion
 export { checkContract as _, readSchemas as a, buildDescriptor as b, detectVerbCollisions as c, hashJson as d, provenanceLines as f, MINIMUM_CONTRACT as g, MAXIMUM_CONTRACT as h, readDocument as i, emit as l, readErrorCatalogue as m, generate as n, emitSchemas as o, emitErrorCodes as p, schemasOutputPath as r, Emitter as s, check as t, deriveProvenance as u, DescriptorBuilder as v, buildAtomic as y };
 
-//# sourceMappingURL=src-CKsM7dXw.mjs.map
+//# sourceMappingURL=src-DhZyiWge.mjs.map