@haddowg/json-api-codegen 1.6.0 → 1.7.0

package/dist/{src-C2INS1Wd.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,108 @@ 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
+/**
+* Helpers for writing strings read from the OpenAPI document into generated TypeScript. Every
+* name, literal and comment the emitters take from the document goes through one of these.
+*/
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Line terminators as JavaScript counts them. */
+const LINE_BREAK = /\r\n|[\n\r\u2028\u2029]/;
+/** A string as a TS string literal. U+2028/U+2029 are escaped too, which JSON leaves raw. */
+function stringLiteral(value) {
+	return JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+/** True when a string is a bare identifier. */
+function isIdentifier(value) {
+	return IDENTIFIER.test(value);
+}
+/**
+* A property key for an object literal or an interface: bare when it's an identifier, quoted
+* otherwise. `__proto__` is written as a computed key, which a runtime literal keeps as an own
+* property instead of setting the prototype.
+*/
+function propertyKey(name) {
+	if (name === "__proto__") return `[${stringLiteral(name)}]`;
+	return isIdentifier(name) ? name : stringLiteral(name);
+}
+/** Text that can sit inside a block comment: any `*\/` is broken up so it can't close it. */
+function commentText(text) {
+	return text.replace(/\*\//g, "* /");
+}
+/** {@link commentText} split into lines, for a multi-line block comment. */
+function commentLines(text) {
+	return commentText(text).split(LINE_BREAK);
+}
+/** {@link commentText} on one line, for a single comment line such as the provenance header. */
+function commentLine(text) {
+	return commentText(text).split(LINE_BREAK).join(" ");
+}
+/** Words a type alias can't be named: reserved words and the built-in type names. */
+const RESERVED_TYPE_NAMES = /* @__PURE__ */ new Set([
+	"any",
+	"bigint",
+	"boolean",
+	"break",
+	"case",
+	"catch",
+	"class",
+	"const",
+	"continue",
+	"debugger",
+	"default",
+	"delete",
+	"do",
+	"else",
+	"enum",
+	"export",
+	"extends",
+	"false",
+	"finally",
+	"for",
+	"function",
+	"if",
+	"implements",
+	"import",
+	"in",
+	"instanceof",
+	"interface",
+	"let",
+	"never",
+	"new",
+	"null",
+	"number",
+	"object",
+	"package",
+	"private",
+	"protected",
+	"public",
+	"return",
+	"static",
+	"string",
+	"super",
+	"switch",
+	"symbol",
+	"this",
+	"throw",
+	"true",
+	"try",
+	"typeof",
+	"undefined",
+	"unknown",
+	"var",
+	"void",
+	"while",
+	"with",
+	"yield"
+]);
+/** True when `name` can be used as is for an exported type. */
+function isTypeName(name) {
+	return isIdentifier(name) && !RESERVED_TYPE_NAMES.has(name);
 }
 //#endregion
 //#region src/error-codes.ts
@@ -981,24 +1142,20 @@ function readErrorCatalogue(doc) {
 /** A TSDoc block for one code: its description, then each example detail as an `@example`. */
 function codeDoc(entry, indent) {
 	const lines = [];
-	if (entry.description !== void 0) lines.push(...entry.description.split("\n"));
+	if (entry.description !== void 0) lines.push(...commentLines(entry.description));
 	for (const example of entry.examples) {
 		if (lines.length > 0) lines.push("");
 		const text = typeof example === "string" ? example : JSON.stringify(example);
-		lines.push(...`@example ${text}`.split("\n"));
+		lines.push(...commentLines(`@example ${text}`));
 	}
 	if (lines.length === 0) return;
-	if (lines.length === 1) return `${indent}/** ${lines[0].replace(/\*\//g, "* /")} */`;
+	if (lines.length === 1) return `${indent}/** ${lines[0]} */`;
 	return [
 		`${indent}/**`,
-		...lines.map((line) => `${indent} * ${line.replace(/\*\//g, "* /")}`.trimEnd()),
+		...lines.map((line) => `${indent} * ${line}`.trimEnd()),
 		`${indent} */`
 	].join("\n");
 }
-/** A bare object key when the code is a valid identifier, else a quoted one. */
-function codeKey(code) {
-	return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(code) ? code : JSON.stringify(code);
-}
 /**
 * Emit `ErrorCodes`, a const object keyed by every documented code with its TSDoc on the key
 * (editors show TSDoc on an object key, not on a string-literal union member), the `ErrorCode`
@@ -1021,7 +1178,7 @@ function emitErrorCodes(catalogue) {
 		"export const ErrorCodes = {",
 		...catalogue.codes.flatMap((entry) => {
 			const doc = codeDoc(entry, "  ");
-			const member = `  ${codeKey(entry.code)}: ${JSON.stringify(entry.code)},`;
+			const member = `  ${propertyKey(entry.code)}: ${stringLiteral(entry.code)},`;
 			return doc === void 0 ? [member] : [doc, member];
 		}),
 		"} as const",
@@ -1033,7 +1190,7 @@ function emitErrorCodes(catalogue) {
 		"export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes]"
 	].join("\n");
 	const statusLines = [...catalogue.byStatus].map(([status, codes]) => {
-		const members = codes.map((c) => JSON.stringify(c));
+		const members = codes.map((c) => stringLiteral(c));
 		const line = `  ${status}: ${members.length === 0 ? "never" : members.join(" | ")}`;
 		return line.length <= 100 ? line : `  ${status}:\n${members.map((m) => `    | ${m}`).join("\n")}`;
 	});
@@ -1090,12 +1247,12 @@ function deriveProvenance(doc) {
 }
 /**
 * Render the provenance record as the JSDoc header lines stamped into a generated artifact
-* (each already prefixed with ` * `). Deterministic: no timestamp, so re-generating from the
+* (each already prefixed with ` * `), with the document's text kept to one comment line. Deterministic: no timestamp, so re-generating from the
 * same spec yields byte-identical output.
 */
 function provenanceLines(provenance) {
-	const lines = [` * Source spec: ${provenance.source}`, ` * Spec hash:   ${provenance.hash}`];
-	if (provenance.server !== void 0) lines.splice(1, 0, ` * Server:      ${provenance.server}`);
+	const lines = [` * Source spec: ${commentLine(provenance.source)}`, ` * Spec hash:   ${provenance.hash}`];
+	if (provenance.server !== void 0) lines.splice(1, 0, ` * Server:      ${commentLine(provenance.server)}`);
 	return lines;
 }
 //#endregion
@@ -1140,17 +1297,25 @@ function isSchema(value) {
 function pascalCase(value) {
 	return value.split(/[^a-zA-Z0-9]+/).filter((part) => part.length > 0).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 }
-/** Emit a JSON-string literal (used for keys that aren't bare identifiers and enum members). */
-function quote(value) {
-	return JSON.stringify(value);
-}
-/** True when a string is a safe bare object-key identifier. */
-function isIdentifier(value) {
-	return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value);
-}
-function objectKey(value) {
-	return isIdentifier(value) ? value : quote(value);
+/** The identifier stem for a wire type's interfaces, `Type`-prefixed when it would start with a digit. */
+function typeStem(type) {
+	const pascal = pascalCase(type);
+	return /^[A-Za-z]/.test(pascal) ? pascal : `Type${pascal}`;
 }
+/** Names the generated module declares or relies on, which an enum alias must not take. */
+const MODULE_NAMES = [
+	"ActionTypes",
+	"ApiDescriptor",
+	"Attributes",
+	"ClientOptions",
+	"ErrorCode",
+	"ErrorCodeByStatus",
+	"ErrorCodeGuard",
+	"ErrorCodes",
+	"Record",
+	"ResourceMap",
+	"WriteAttributes"
+];
 /**
 * Render a description as a JSDoc comment at the given indent — single-line when it fits,
 * a block otherwise. Returns `undefined` for empty text. Neutralises any `*\/` so a
@@ -1159,7 +1324,7 @@ function objectKey(value) {
 function jsDoc(text, indent) {
 	const trimmed = text?.trim();
 	if (!trimmed) return;
-	const lines = trimmed.replace(/\*\//g, "* /").split("\n");
+	const lines = commentLines(trimmed);
 	if (lines.length === 1) return `${indent}/** ${lines[0]} */`;
 	return [
 		`${indent}/**`,
@@ -1214,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;
@@ -1229,6 +1422,10 @@ var Emitter = class {
 	* already-named attribute type. Populated as interfaces are emitted.
 	*/
 	emittedInterfaces = /* @__PURE__ */ new Set();
+	/** Enum component name -> the alias name it's emitted under. */
+	enumNames = /* @__PURE__ */ new Map();
+	/** Type names already spoken for: the module's own, the per-type interfaces and enum aliases. */
+	takenNames;
 	/** Component names mid-expansion in {@link tsType} — a cycle guard for self/mutually-referential `$ref`s. */
 	expanding = /* @__PURE__ */ new Set();
 	/**
@@ -1237,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;
@@ -1247,6 +1448,50 @@ var Emitter = class {
 		this.schemas = this.doc.components?.schemas ?? {};
 		this.baseByType = this.indexBases();
 		this.provenance = deriveProvenance(source);
+		this.takenNames = new Set(MODULE_NAMES);
+		for (const type of Object.keys(descriptor)) {
+			const stem = typeStem(type);
+			for (const suffix of [
+				"Attributes",
+				"CreateAttributes",
+				"UpdateAttributes"
+			]) this.takenNames.add(`${stem}${suffix}`);
+			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.
+	*/
+	enumName(component) {
+		const known = this.enumNames.get(component);
+		if (known !== void 0) return known;
+		let name = component;
+		if (!isTypeName(component) || this.takenNames.has(component)) {
+			const pascal = pascalCase(component);
+			let stem = /^[A-Za-z]/.test(pascal) ? pascal : `Enum${pascal}`;
+			if (!isTypeName(stem) || this.takenNames.has(stem)) stem = `${stem}Enum`;
+			name = stem;
+			for (let n = 2; this.takenNames.has(name); n++) name = `${stem}${n}`;
+			console.warn(`Enum component ${stringLiteral(component)} can't be used as a TypeScript type name; emitting it as ${name}.`);
+		}
+		this.takenNames.add(name);
+		this.enumNames.set(component, name);
+		return name;
 	}
 	/** Map each declared wire type back to the `Base` of its resource schema. */
 	indexBases() {
@@ -1307,7 +1552,7 @@ var Emitter = class {
 		const base = this.baseByType.get(type);
 		const props = base ? this.schemas[`${base}Attributes`]?.properties : void 0;
 		const fields = Object.keys(this.descriptor[type].attributes);
-		return this.renderInterface(`${pascalCase(type)}Attributes`, props, fields, () => true);
+		return this.renderInterface(`${typeStem(type)}Attributes`, props, fields, () => true);
 	}
 	/**
 	* The per-type WRITE attribute interfaces — `<Pascal>CreateAttributes` and
@@ -1319,7 +1564,7 @@ var Emitter = class {
 	writeAttributeInterfaces(type) {
 		const base = this.baseByType.get(type);
 		if (base === void 0) return [];
-		const pascal = pascalCase(type);
+		const pascal = typeStem(type);
 		const out = [];
 		const create = this.schemas[`${base}CreateAttributes`];
 		if (create !== void 0) {
@@ -1346,7 +1591,7 @@ var Emitter = class {
 		for (const type of Object.keys(this.descriptor)) {
 			const actions = this.descriptor[type]?.actions;
 			if (actions === void 0) continue;
-			const pascal = pascalCase(type);
+			const pascal = typeStem(type);
 			for (const [actionName, action] of Object.entries(actions)) {
 				const member = `${pascal}${pascalCase(actionName)}`;
 				const names = {};
@@ -1360,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();
@@ -1373,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
@@ -1390,9 +1740,11 @@ 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}`);
-				actionLines.push(`    ${objectKey(actionName)}: { ${members.join("; ")} }`);
+				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(`  ${objectKey(type)}: {\n${actionLines.join("\n")}\n  }`);
+			typeLines.push(`  ${propertyKey(type)}: {\n${actionLines.join("\n")}\n  }`);
 		}
 		if (typeLines.length === 0) return "export interface ActionTypes {}";
 		return `export interface ActionTypes {\n${typeLines.join("\n")}\n}`;
@@ -1440,10 +1792,10 @@ var Emitter = class {
 			if (schema.oneOf !== void 0) for (const arm of schema.oneOf) {
 				const kind = isSchema(arm.properties?.["kind"]) ? arm.properties["kind"].const : void 0;
 				const members = this.pageMemberLimits(arm, "      ");
-				if (typeof kind === "string" && members.length > 0) body.push(`    ${objectKey(kind)}: {\n${members.join("\n")}\n    },`);
+				if (typeof kind === "string" && members.length > 0) body.push(`    ${propertyKey(kind)}: {\n${members.join("\n")}\n    },`);
 			}
 			else body = this.pageMemberLimits(schema, "    ");
-			if (body.length > 0) typeLines.push(`  ${objectKey(type)}: {\n${body.join("\n")}\n  },`);
+			if (body.length > 0) typeLines.push(`  ${propertyKey(type)}: {\n${body.join("\n")}\n  },`);
 		}
 		return `${[
 			"/**",
@@ -1468,7 +1820,7 @@ var Emitter = class {
 			if (limits.length === 0) continue;
 			const doc = jsDoc(memberDoc(prop), indent);
 			if (doc !== void 0) lines.push(doc);
-			lines.push(`${indent}${objectKey(name)}: { ${limits.join(", ")} },`);
+			lines.push(`${indent}${propertyKey(name)}: { ${limits.join(", ")} },`);
 		}
 		return lines;
 	}
@@ -1485,7 +1837,7 @@ var Emitter = class {
 			const doc = isSchema(schema) ? jsDoc(memberDoc(schema), "  ") : void 0;
 			if (doc) lines.push(doc);
 			const optional = required(field) ? "" : "?";
-			lines.push(`  ${objectKey(field)}${optional}: ${tsType}`);
+			lines.push(`  ${propertyKey(field)}${optional}: ${tsType}`);
 		}
 		this.emittedInterfaces.add(name);
 		if (lines.length === 0) return `export interface ${name} {}`;
@@ -1498,7 +1850,7 @@ var Emitter = class {
 			const resolved = target ? this.schemas[target] : void 0;
 			if (target && resolved && Array.isArray(resolved.enum)) {
 				this.usedEnums.set(target, resolved);
-				return target;
+				return this.enumName(target);
 			}
 			if (target && this.emittedInterfaces.has(target)) return target;
 			if (resolved === void 0 || target === void 0 || this.expanding.has(target)) return "unknown";
@@ -1523,7 +1875,7 @@ var Emitter = class {
 	}
 	/** The non-nullable TS type for the declared JSON type(s). */
 	baseTsType(schema, types) {
-		if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum.map((value) => quote(String(value))).join(" | ");
+		if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum.map((value) => stringLiteral(String(value))).join(" | ");
 		if (types.length === 0) return "unknown";
 		const mapped = types.map((t) => this.scalarOrComposite(schema, t));
 		return [...new Set(mapped)].join(" | ");
@@ -1548,7 +1900,7 @@ var Emitter = class {
 		for (const [name, prop] of Object.entries(props)) {
 			if (!isSchema(prop)) continue;
 			const optional = required.has(name) ? "" : "?";
-			members.push(`${objectKey(name)}${optional}: ${this.tsType(prop)}`);
+			members.push(`${propertyKey(name)}${optional}: ${this.tsType(prop)}`);
 		}
 		if (members.length === 0) return "Record<string, unknown>";
 		return `{ ${members.join("; ")} }`;
@@ -1565,7 +1917,8 @@ var Emitter = class {
 		if (this.usedEnums.size === 0) return;
 		return [...this.usedEnums.keys()].sort().map((name) => {
 			const schema = this.usedEnums.get(name);
-			const alias = `export type ${name} = ${(schema.enum ?? []).map((value) => quote(String(value))).join(" | ")}`;
+			const union = (schema.enum ?? []).map((value) => stringLiteral(String(value))).join(" | ");
+			const alias = `export type ${this.enumName(name)} = ${union}`;
 			const doc = jsDoc(this.enumDoc(schema), "");
 			return doc ? `${doc}\n${alias}` : alias;
 		}).join("\n\n");
@@ -1588,7 +1941,7 @@ var Emitter = class {
 	* argument to the runtime factory).
 	*/
 	attributesMap() {
-		return `export interface Attributes {\n${Object.keys(this.descriptor).map((type) => `  ${objectKey(type)}: ${pascalCase(type)}Attributes`).join("\n")}\n}`;
+		return `export interface Attributes {\n${Object.keys(this.descriptor).map((type) => `  ${propertyKey(type)}: ${typeStem(type)}Attributes`).join("\n")}\n}`;
 	}
 	/**
 	* Emit the `WriteAttributes` interface mapping each writable wire type to its
@@ -1603,21 +1956,21 @@ var Emitter = class {
 			const hasCreate = base !== void 0 && this.schemas[`${base}CreateAttributes`] !== void 0;
 			const hasUpdate = base !== void 0 && this.schemas[`${base}UpdateAttributes`] !== void 0;
 			if (!hasCreate && !hasUpdate) continue;
-			const pascal = pascalCase(type);
+			const pascal = typeStem(type);
 			const members = [];
 			if (hasCreate) members.push(`create: ${pascal}CreateAttributes`);
 			if (hasUpdate) members.push(`update: ${pascal}UpdateAttributes`);
-			lines.push(`  ${objectKey(type)}: { ${members.join("; ")} }`);
+			lines.push(`  ${propertyKey(type)}: { ${members.join("; ")} }`);
 		}
 		if (lines.length === 0) return "export interface WriteAttributes {}";
 		return `export interface WriteAttributes {\n${lines.join("\n")}\n}`;
 	}
 	/** 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)) {
@@ -1627,9 +1980,14 @@ 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}${objectKey(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 JSON.stringify(value);
+		return typeof value === "string" ? stringLiteral(value) : JSON.stringify(value);
 	}
 	boundFactory() {
 		return [
@@ -1688,7 +2046,7 @@ function header(bundle) {
 	].join("\n");
 }
 function body(bundle) {
-	return `export const schemas = ${JSON.stringify(bundle, null, 2)} as const`;
+	return `export const schemas = ${JSON.stringify(bundle, null, 2).replace(/^(\s*)"__proto__":/gm, "$1[\"__proto__\"]:").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029")} as const`;
 }
 //#endregion
 //#region src/reader.ts
@@ -1832,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-C2INS1Wd.mjs.map
+//# sourceMappingURL=src-DhZyiWge.mjs.map