@kizunajs/kotlin 2.0.0-beta.2 → 2.0.0-beta.20

package/README.md

@@ -10,8 +10,25 @@ pnpm add -D @kizunajs/kotlin
 
 ## Usage
 
+Name the client in your config, and `kizuna generate` writes it with the rest:
+
+```ts
+import { kotlinClient } from '@kizunajs/kotlin';
+
+export default defineConfig({
+    routes,
+    clients: [
+        kotlinClient({
+            output: '../android/app/src/main/kotlin/com/example/APIClient.kt',
+            namespace: 'API',
+            package: 'com.example',
+        }),
+    ],
+});
+```
+
 ```sh
-kizuna-kotlin generate --config kizuna.config.ts --out android/app/src/main/kotlin/com/example/APIClient.kt --namespace-name API --package com.example
+kizuna generate
 ```
 
 ## Documentation

package/dist/cli.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_generator = require("./generator-s2pn7vqP.cjs");
+const require_generator = require("./generator-Bg4HlRb3.cjs");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 let node_util = require("node:util");

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as generateKotlinClient } from "./generator-BvNpSarY.mjs";
+import { t as generateKotlinClient } from "./generator-D4GvH1-a.mjs";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { parseArgs } from "node:util";

package/dist/{generator-s2pn7vqP.cjs → generator-Bg4HlRb3.cjs}

@@ -56,6 +56,7 @@ var TypeRegistry = class {
 	explicitIds = /* @__PURE__ */ new Set();
 	sealedVariantPayloads = /* @__PURE__ */ new Set();
 	sealedVariantPaths = /* @__PURE__ */ new Map();
+	brands = /* @__PURE__ */ new Map();
 	usesJsonElement = false;
 	constructor(camelCaseProperties = false, unknownEnumCase = false) {
 		this.camelCaseProperties = camelCaseProperties;
@@ -99,6 +100,15 @@ var TypeRegistry = class {
 	sealedVariantPath(name) {
 		return this.sealedVariantPaths.get(name);
 	}
+	addBrand(brand) {
+		const existing = this.brands.get(brand.name);
+		if (existing !== void 0 && existing.rawType !== brand.rawType) throw new Error(`@kizunajs/kotlin: brand ${stringify(brand.name)} wraps both ${existing.rawType} and ${brand.rawType}. Give each its own name.`);
+		if (this.types.has(brand.name)) throw new Error(`@kizunajs/kotlin: brand ${stringify(brand.name)} has the same name as a model. Give each its own name.`);
+		this.brands.set(brand.name, brand);
+	}
+	allBrands() {
+		return Array.from(this.brands.values());
+	}
 	warnJsonElement(hint, reason) {
 		this.usesJsonElement = true;
 		this.warningSet.add(`${hint}: ${reason}`);
@@ -117,8 +127,7 @@ const propertyName = (key, camelCase) => {
 	if (!camel) return "field";
 	return /^[0-9]/.test(camel) ? `_${camel}` : camel;
 };
-const objectFields = (schema, registry, hint) => {
-	const shape = (0, kizunajs_generator.readObjectShape)(schema) ?? {};
+const objectFields = (schema, registry, hint, shape = (0, kizunajs_generator.readObjectShape)(schema) ?? {}) => {
 	const fields = [];
 	const seen = /* @__PURE__ */ new Map();
 	for (const [key, value] of Object.entries(shape)) {
@@ -133,6 +142,7 @@ const objectFields = (schema, registry, hint) => {
 			wireName: key,
 			type: result.expression,
 			optional: result.optional,
+			requiredNullable: result.requiredNullable,
 			description: (0, kizunajs_generator.readMetaDescription)(value),
 			isFile: result.isFile,
 			deprecated: deprecation !== void 0,
@@ -142,12 +152,38 @@ const objectFields = (schema, registry, hint) => {
 	return fields;
 };
 const stringify = (value) => JSON.stringify(value);
+const BRANDABLE_TYPES = new Set([
+	"String",
+	"Int",
+	"Long",
+	"Double",
+	"Boolean",
+	"Instant"
+]);
 const mapType = (schema, registry, hint) => {
+	const result = mapUnbrandedType(schema, registry, hint);
+	const brand = (0, kizunajs_generator.readMetaBrand)(schema);
+	if (brand === void 0 || !BRANDABLE_TYPES.has(result.expression)) return result;
+	const name = (0, kizunajs_generator.sanitizeIdentifier)(brand);
+	registry.addBrand({
+		name,
+		rawType: result.expression
+	});
+	return {
+		expression: name,
+		optional: false
+	};
+};
+const mapUnbrandedType = (schema, registry, hint) => {
 	if ((0, kizunajs_generator.isFileSchema)(schema)) return {
 		expression: "MultipartFile",
 		optional: false,
 		isFile: true
 	};
+	if ((0, kizunajs_generator.isBinarySchema)(schema)) return {
+		expression: "ByteArray",
+		optional: false
+	};
 	const id = (0, kizunajs_generator.readMetaId)(schema);
 	const def = (0, kizunajs_generator.readDef)(schema);
 	const discriminated = (0, kizunajs_generator.readDiscriminatedUnion)(schema);
@@ -223,12 +259,13 @@ const mapType = (schema, registry, hint) => {
 			optional: false
 		};
 	}
-	const { inner, optional } = (0, kizunajs_generator.unwrapOptionalWrappers)(schema);
-	if (optional) {
+	const { inner, optional, nullable } = (0, kizunajs_generator.unwrapOptionalWrappers)(schema);
+	if (optional || nullable) {
 		const innerResult = mapType(inner, registry, hint);
 		return {
 			expression: innerResult.expression.endsWith("?") ? innerResult.expression : `${innerResult.expression}?`,
 			optional: true,
+			requiredNullable: nullable && !optional,
 			isFile: innerResult.isFile
 		};
 	}
@@ -277,8 +314,9 @@ const mapType = (schema, registry, hint) => {
 					optional: false
 				};
 			}
+			const elementType = mapType(element, registry, `${hint}Item`).expression.replace(/\?$/, "");
 			return {
-				expression: `List<${mapType(element, registry, `${hint}Item`).expression.replace(/\?$/, "")}>`,
+				expression: `List<${(0, kizunajs_generator.unwrapOptionalWrappers)(element).nullable ? `${elementType}?` : elementType}>`,
 				optional: false
 			};
 		}
@@ -412,6 +450,7 @@ const sanitizeCaseName = (literal) => {
 const collectObjectFields = (schema, registry, hint) => {
 	return objectFields(schema, registry, hint);
 };
+const hasDefault = (field) => field.optional && field.requiredNullable !== true;
 const objectFieldCount = (schema) => {
 	return Object.keys((0, kizunajs_generator.readObjectShape)(schema) ?? {}).length;
 };
@@ -576,7 +615,7 @@ const buildRouteMethod = (routeKey, route, registry, deprecated, deprecationMess
 		stream
 	};
 };
-const kotlinGenerator = (0, kizunajs_generator.createGenerator)((options, _api) => {
+const kotlinRoutesWalk = (options) => {
 	const flatMethods = [];
 	const groupMap = /* @__PURE__ */ new Map();
 	return {
@@ -608,7 +647,7 @@ const kotlinGenerator = (0, kizunajs_generator.createGenerator)((options, _api)
 			};
 		}
 	};
-});
+};
 const KOTLIN_KEYWORDS = new Set([
 	"as",
 	"break",
@@ -642,6 +681,10 @@ const KOTLIN_KEYWORDS = new Set([
 const escapeKeyword = (name) => {
 	return KOTLIN_KEYWORDS.has(name) ? `\`${name}\`` : name;
 };
+const defaultArgument = (field) => {
+	if (!hasDefault(field)) return "";
+	return " = null";
+};
 const optionalize = (type, optional) => {
 	if (!optional) return type;
 	return type.endsWith("?") ? type : `${type}?`;
@@ -653,8 +696,13 @@ const KOTLIN_PRIMITIVE_TYPES = new Set([
 	"Long",
 	"Boolean",
 	"Instant",
-	"Unit"
+	"Unit",
+	"ByteArray"
 ]);
+/**
+* How a response body is read. Raw bytes are the body already.
+*/
+const decodeBody = (resolved) => resolved === "ByteArray" ? "data" : `json.decodeFromString<${resolved}>(data.decodeToString())`;
 const resolveType = (typeName, currentOperation, context, scope = "client") => {
 	const { operationTypeMap, namespaceName, clientName, fileLevelTypeNames } = context;
 	const optional = typeName.endsWith("?");
@@ -797,7 +845,7 @@ const emitDataClass = (writer, type, ownedTypeMap, ownedTypeLookup, registryName
 	if (!hasFile) writer.line("@Serializable");
 	const params = adjustedFields.map((field) => {
 		const typeExpression = optionalize(field.type, field.optional);
-		const defaultPart = field.optional ? " = null" : "";
+		const defaultPart = defaultArgument(field);
 		const serialNameAnnotation = needsSerialName && (field.name !== field.wireName || KOTLIN_KEYWORDS.has(field.name)) ? `@SerialName(${stringLiteral(field.wireName)}) ` : "";
 		return `${field.deprecated ? `${deprecatedAnnotation(field.deprecationMessage)} ` : ""}${serialNameAnnotation}val ${escapeKeyword(field.name)}: ${typeExpression}${defaultPart}`;
 	});
@@ -890,7 +938,7 @@ const emitSealedClass = (writer, type, registry, ownedTypeMap, ownedTypeLookup)
 					const params = fields.map((field) => {
 						const variantPath = registry.sealedVariantPath(variant.payloadType) ?? variant.payloadType;
 						const typeExpression = optionalize(relativeOwnedPath(field.type, ownedTypeMap, variantPath, registry) ?? ownedTypePath(field.type, ownedTypeMap, registry), field.optional);
-						const defaultPart = field.optional ? " = null" : "";
+						const defaultPart = defaultArgument(field);
 						return `val ${escapeKeyword(field.name)}: ${typeExpression}${defaultPart}`;
 					});
 					if (params.length === 1) writer.line(`data class ${variant.caseName}(${params[0]}) : ${type.name}`);
@@ -927,6 +975,16 @@ const emitType = (writer, type, ownedTypeMap = /* @__PURE__ */ new Map(), ownedT
 	else if (type.kind === "enum-class") emitEnumClass(writer, type.name, type.cases, type.unknownCase, type.description);
 	else if (registry) emitSealedClass(writer, type, registry, ownedTypeMap, ownedTypeLookup);
 };
+/**
+* A brand as a value class that serializes and prints as the bare value.
+*/
+const emitBrand = (writer, brand) => {
+	writer.line("@Serializable");
+	writer.line("@JvmInline");
+	writer.block(`value class ${brand.name}(val value: ${brand.rawType})`, () => {
+		writer.line(`override fun toString(): String = ${brand.rawType === "String" ? "value" : "value.toString()"}`);
+	});
+};
 const emitTypes = (writer, types, ownedTypeMap = /* @__PURE__ */ new Map(), ownedTypeLookup = /* @__PURE__ */ new Map(), registry) => {
 	for (const type of types) emitType(writer, type, ownedTypeMap, ownedTypeLookup, void 0, registry);
 };
@@ -1002,7 +1060,7 @@ const emitOperationResultTypes = (writer, method, context) => {
 			writer.line(") {");
 			writer.indent(() => {
 				writer.line("/** How far along the call is. */");
-				writer.line("enum class State { Running, Done, Failed }");
+				writer.line("enum class State { Running, NeedsApproval, Done, Failed }");
 			});
 			writer.line("}");
 			writer.blank();
@@ -1012,7 +1070,12 @@ const emitOperationResultTypes = (writer, method, context) => {
 				writer.block("for (event in events)", () => {
 					writer.line("when (event) {");
 					writer.indent(() => {
-						writer.line("is Event.ToolCall -> calls[event.data.id] = (calls[event.data.id] ?: ToolCallRecord(event.data.id, event.data.name)).copy(call = event.data)");
+						writer.line("is Event.ToolCall -> {");
+						writer.indent(() => {
+							writer.line("val tracked = (calls[event.data.id] ?: ToolCallRecord(event.data.id, event.data.name)).copy(call = event.data)");
+							writer.line("calls[event.data.id] = if (event.data.needsApproval == true && tracked.state == ToolCallRecord.State.Running) tracked.copy(state = ToolCallRecord.State.NeedsApproval) else tracked");
+						});
+						writer.line("}");
 						writer.line("is Event.ToolResult -> calls[event.data.id] = (calls[event.data.id] ?: ToolCallRecord(event.data.id, event.data.name)).copy(state = ToolCallRecord.State.Done, result = event.data)");
 						if (eventNames.has("tool_error")) writer.line("is Event.ToolError -> calls[event.data.id] = (calls[event.data.id] ?: ToolCallRecord(event.data.id, event.data.name.wireValue)).copy(state = ToolCallRecord.State.Failed, message = event.data.message)");
 						writer.line("else -> Unit");
@@ -1074,7 +1137,7 @@ const groupTypeRef = (operationName, className, context) => `${context.clientNam
 const groupMemberAccessor = (groupLabel, field) => `${groupLabel}.${escapeKeyword(field.name)}`;
 const groupClassField = (field) => {
 	const typeExpression = optionalize(field.type, field.optional);
-	const defaultPart = field.optional ? " = null" : "";
+	const defaultPart = defaultArgument(field);
 	return `val ${escapeKeyword(field.name)}: ${typeExpression}${defaultPart}`;
 };
 const emitGroupClass = (writer, className, fields, method, context) => {
@@ -1133,13 +1196,13 @@ const methodChannels = (method) => {
 	if (method.query.length > 0) channels.push({
 		varName: "query",
 		className: "Query",
-		required: method.query.some((field) => !field.optional),
+		required: method.query.some((field) => !hasDefault(field)),
 		fields: method.query
 	});
 	if (method.headers.length > 0) channels.push({
 		varName: "headers",
 		className: "Headers",
-		required: method.headers.some((field) => !field.optional),
+		required: method.headers.some((field) => !hasDefault(field)),
 		fields: method.headers
 	});
 	if (hasBodyGroup(method)) {
@@ -1188,7 +1251,7 @@ const emitArgsScaffolding = (writer, method, context) => {
 	};
 	const factorySignature = (channel) => channel.fields.map((field) => {
 		const typeExpression = optionalize(field.type, field.optional);
-		const defaultPart = field.optional ? " = null" : "";
+		const defaultPart = defaultArgument(field);
 		return `${escapeKeyword(field.name)}: ${typeExpression}${defaultPart}`;
 	}).join(", ");
 	const factoryConstruction = (channel) => {
@@ -1245,10 +1308,16 @@ const emitBodyEncoding = (writer, method, context) => {
 	if (body.kind === "multipart") {
 		writer.line("val multipartBuilder = MultipartBody.Builder().setType(MultipartBody.FORM)");
 		for (const field of body.multipartFields) {
-			const accessor = groupMemberAccessor("body", field);
-			const isFlattenedFile = body.flattened.find((flatField) => flatField.name === field.name)?.isFile === true;
-			if (field.isFile || isFlattenedFile) writer.line(`multipartBuilder.addFormDataPart(${stringLiteral(field.wireName)}, ${accessor}.filename, ${accessor}.data.toRequestBody(${accessor}.mimeType.toMediaType()))`);
-			else writer.line(`multipartBuilder.addFormDataPart(${stringLiteral(field.wireName)}, ${accessor}.toString())`);
+			const flattenedField = body.flattened.find((flatField) => flatField.name === field.name);
+			const isFile = field.isFile || flattenedField?.isFile === true;
+			const append = (accessor) => {
+				if (isFile) writer.line(`multipartBuilder.addFormDataPart(${stringLiteral(field.wireName)}, ${accessor}.filename, ${accessor}.data.toRequestBody(${accessor}.mimeType.toMediaType()))`);
+				else writer.line(`multipartBuilder.addFormDataPart(${stringLiteral(field.wireName)}, ${accessor}.toString())`);
+			};
+			if (flattenedField?.optional === true) writer.block(`if (${groupMemberAccessor("body", field)} != null)`, () => {
+				append(groupMemberAccessor("body", field));
+			});
+			else append(groupMemberAccessor("body", field));
 		}
 		writer.line("requestBody = multipartBuilder.build()");
 		return;
@@ -1324,7 +1393,7 @@ const emitMethodBody = (writer, method, context) => {
 		else setHeader(accessor);
 	}
 	writer.line("requestInterceptor?.invoke(requestBuilder)");
-	writer.line("val httpResponse = Kizuna.execute(client, requestBuilder.build())");
+	writer.line("val httpResponse = Kizuna.send(client, requestBuilder.build(), retry)");
 	if (method.stream) {
 		emitStreamMethodTail(writer, method, context);
 		return;
@@ -1344,7 +1413,7 @@ const emitMethodBody = (writer, method, context) => {
 				writer.indent(() => {
 					const resolved = resolveType(successResponse.type, method.operationName, context);
 					writer.block("try", () => {
-						writer.line(`val payload = json.decodeFromString<${resolved}>(data.decodeToString())`);
+						writer.line(`val payload = ${decodeBody(resolved)}`);
 						const bodyExpr = isMultiSuccess ? `${operationRef}.Success.Status${successResponse.status}(payload)` : "payload";
 						if (hasHeaders) {
 							for (const field of successResponse.responseHeaders) writer.line(`val ${escapeKeyword(field.name)} = httpResponse.header(${stringLiteral(field.wireName)})`);
@@ -1381,7 +1450,7 @@ const emitErrorBranches = (writer, method, context) => {
 					const resolved = resolveType(errorCase.type, method.operationName, context);
 					writer.line("val payload = try {");
 					writer.indent(() => {
-						writer.line(`json.decodeFromString<${resolved}>(data.decodeToString())`);
+						writer.line(decodeBody(resolved));
 					});
 					writer.line(`} catch (error: Exception) { throw ${failureRef}.Decoding(error, statusCode, data) }`);
 					writer.line(`throw ${failureRef}.${caseName}(body = payload)`);
@@ -1394,7 +1463,7 @@ const emitErrorBranches = (writer, method, context) => {
 						const resolved = resolveType(errorCase.type, method.operationName, context);
 						writer.line(`val ${errorCase.caseName} = try {`);
 						writer.indent(() => {
-							writer.line(`json.decodeFromString<${resolved}>(data.decodeToString())`);
+							writer.line(decodeBody(resolved));
 						});
 						writer.line("} catch (_: Exception) { null }");
 						writer.line(`if (${errorCase.caseName} != null) throw ${failureRef}.${caseName}(body = ${errorCase.caseName})`);
@@ -1476,7 +1545,7 @@ const emitSubClientMethod = (writer, method, context) => {
 };
 const emitSubClientClass = (writer, group, clientName, context) => {
 	writer.blank();
-	writer.block(`class ${group.className}(private val client: OkHttpClient, private val baseUrl: String, private val json: Json, private val requestContextHeaders: Map<String, String>, private val requestInterceptor: (suspend (Request.Builder) -> Unit)?, private val responseInterceptor: (suspend (Request, Response) -> Unit)?)`, () => {
+	writer.block(`class ${group.className}(private val client: OkHttpClient, private val baseUrl: String, private val json: Json, private val requestContextHeaders: Map<String, String>, private val requestInterceptor: (suspend (Request.Builder) -> Unit)?, private val responseInterceptor: (suspend (Request, Response) -> Unit)?, private val retry: ${clientName}.RetryPolicy?)`, () => {
 		for (const method of group.methods) {
 			writer.blank();
 			emitSubClientMethod(writer, method, context);
@@ -1581,6 +1650,47 @@ const emitKizunaObject = (writer, options) => {
 			writer.line("}");
 		});
 		writer.blank();
+		writer.block(`suspend fun send(client: OkHttpClient, request: Request, retry: ${options.clientName}.RetryPolicy?): Response`, () => {
+			writer.line("val idempotent = request.method in setOf(\"GET\", \"HEAD\", \"OPTIONS\", \"PUT\", \"DELETE\")");
+			writer.line("val policy = retry?.takeIf { idempotent && request.body?.isOneShot() != true }");
+			writer.line("var attempt = 1");
+			writer.block("while (true)", () => {
+				writer.line("val response = try {");
+				writer.line("    execute(client, request)");
+				writer.line("} catch (error: java.io.IOException) {");
+				writer.line("    val delay = policy?.let { retryDelay(it, attempt, null) } ?: throw error");
+				writer.line("    kotlinx.coroutines.delay(delay)");
+				writer.line("    attempt += 1");
+				writer.line("    continue");
+				writer.line("}");
+				writer.line("val delay = policy?.let { retryDelay(it, attempt, response) } ?: return response");
+				writer.line("response.close()");
+				writer.line("kotlinx.coroutines.delay(delay)");
+				writer.line("attempt += 1");
+			});
+		});
+		writer.blank();
+		writer.block(`fun retryDelay(policy: ${options.clientName}.RetryPolicy, attempt: Int, response: Response?): Long?`, () => {
+			writer.line("if (attempt >= policy.maximumAttempts) return null");
+			writer.line("val ceiling = minOf(policy.maximumDelay.inWholeMilliseconds, policy.initialDelay.inWholeMilliseconds shl (attempt - 1))");
+			writer.line("val backoff = (Math.random() * ceiling).toLong()");
+			writer.line("if (response == null) return backoff");
+			writer.line("if (response.code != 429 && response.code != 503) return null");
+			writer.line("val asked = retryAfter(response.header(\"Retry-After\")) ?: return backoff");
+			writer.line("return if (asked <= policy.maximumDelay.inWholeMilliseconds) asked else null");
+		});
+		writer.blank();
+		writer.block("fun retryAfter(header: String?): Long?", () => {
+			writer.line("val value = header?.trim() ?: return null");
+			writer.line("value.toLongOrNull()?.let { return if (it >= 0) it * 1000 else null }");
+			writer.line("val date = try {");
+			writer.line("    java.time.ZonedDateTime.parse(value, java.time.format.DateTimeFormatter.RFC_1123_DATE_TIME)");
+			writer.line("} catch (_: java.time.format.DateTimeParseException) {");
+			writer.line("    return null");
+			writer.line("}");
+			writer.line("return maxOf(0L, date.toInstant().toEpochMilli() - System.currentTimeMillis())");
+		});
+		writer.blank();
 		writer.block("suspend fun execute(client: OkHttpClient, request: Request): Response", () => {
 			writer.line("return kotlinx.coroutines.suspendCancellableCoroutine { continuation ->");
 			writer.indent(() => {
@@ -1608,20 +1718,34 @@ const emitClient = (writer, config, partition, context, typesByOperation, regist
 	const allMethods = [...flatMethods, ...groups.flatMap((group) => group.methods)];
 	const usesMultipart = allMethods.some((method) => method.body?.kind === "multipart");
 	const contextFields = context.requestContextFields;
-	const contextRequired = contextFields.some((field) => !field.optional);
+	const contextRequired = contextFields.some((field) => !hasDefault(field));
 	const contextParam = contextFields.length > 0 ? `requestContext: RequestContext${contextRequired ? "" : " = RequestContext()"}, ` : "";
 	writer.blank();
-	writer.block(`class ${clientName}(private val baseUrl: String, ${contextParam}private val client: OkHttpClient = OkHttpClient(), private val json: Json = Json { ignoreUnknownKeys = true }, private val requestInterceptor: (suspend (Request.Builder) -> Unit)? = null, private val responseInterceptor: (suspend (Request, Response) -> Unit)? = null)`, () => {
+	writer.block(`class ${clientName}(private val baseUrl: String, ${contextParam}private val client: OkHttpClient = OkHttpClient(), private val json: Json = Json { ignoreUnknownKeys = true }, private val requestInterceptor: (suspend (Request.Builder) -> Unit)? = null, private val responseInterceptor: (suspend (Request, Response) -> Unit)? = null, private val retry: RetryPolicy? = null)`, () => {
 		if (contextFields.length > 0) {
 			writer.blank();
 			writer.line("/** Values sent as headers on every request, from the api's request context. */");
-			emitConstructorClass(writer, "data class RequestContext", contextFields.map((field) => `val ${escapeKeyword(field.name)}: ${field.type}${field.optional ? " = null" : ""}`));
+			emitConstructorClass(writer, "data class RequestContext", contextFields.map((field) => `val ${escapeKeyword(field.name)}: ${field.type}${defaultArgument(field)}`));
 			writer.blank();
 			writer.block("private val requestContextHeaders: Map<String, String> = buildMap", () => {
 				for (const field of contextFields) if (field.optional) writer.line(`if (requestContext.${escapeKeyword(field.name)} != null) put(${stringLiteral(field.wireName)}, requestContext.${escapeKeyword(field.name)}!!)`);
 				else writer.line(`put(${stringLiteral(field.wireName)}, requestContext.${escapeKeyword(field.name)})`);
 			});
 		}
+		writer.blank();
+		writer.line("/**");
+		writer.line(" * Retries a GET, HEAD, OPTIONS, PUT or DELETE that failed on the network or was answered 429 or 503,");
+		writer.line(" * waiting what Retry-After asks or backing off.");
+		writer.line(" *");
+		writer.line(" * @property maximumAttempts Attempts in all, the first included.");
+		writer.line(" * @property initialDelay What the first backoff waits at most.");
+		writer.line(" * @property maximumDelay What any wait may take.");
+		writer.line(" */");
+		emitConstructorClass(writer, "data class RetryPolicy", [
+			"val maximumAttempts: Int = 3",
+			"val initialDelay: kotlin.time.Duration = 500.milliseconds",
+			"val maximumDelay: kotlin.time.Duration = 30.seconds"
+		]);
 		if (usesMultipart) {
 			writer.blank();
 			emitConstructorClass(writer, "data class MultipartFile", [
@@ -1677,7 +1801,7 @@ const emitClient = (writer, config, partition, context, typesByOperation, regist
 		}
 		if (groups.length > 0) for (const group of groups) {
 			writer.blank();
-			writer.line(`val ${escapeKeyword(group.propertyName)} = ${group.className}(client, baseUrl, json, ${contextFields.length > 0 ? "requestContextHeaders" : "emptyMap()"}, requestInterceptor, responseInterceptor)`);
+			writer.line(`val ${escapeKeyword(group.propertyName)} = ${group.className}(client, baseUrl, json, ${contextFields.length > 0 ? "requestContextHeaders" : "emptyMap()"}, requestInterceptor, responseInterceptor, retry)`);
 		}
 		for (const method of flatMethods) {
 			writer.blank();
@@ -1685,21 +1809,8 @@ const emitClient = (writer, config, partition, context, typesByOperation, regist
 		}
 	});
 };
-/**
-* Generate a Kotlin API client from a Kizuna api.
-*
-* @param api - What `defineConfig` assembled.
-* @param config - Override the generated names:
-*   - `namespaceName`: the object wrapping shared types.
-*   - `packageName`: optional package declaration for the generated file.
-*/
-const generateKotlinClient = (api, config) => {
-	const { namespaceName, packageName, camelCaseProperties = false, unknownEnumCase = false } = config;
-	const registry = new TypeRegistry(camelCaseProperties, unknownEnumCase);
-	const partition = kotlinGenerator(api, {
-		namespaceName,
-		registry
-	});
+const renderKotlinClient = (api, partition, registry, config) => {
+	const { namespaceName, packageName, camelCaseProperties = false } = config;
 	const allMethods = [...partition.flatMethods, ...partition.groups.flatMap((group) => group.methods)];
 	const operationTypeMap = buildOperationTypeMap(allMethods, registry);
 	const clientName = `${namespaceName}Client`;
@@ -1735,6 +1846,8 @@ const generateKotlinClient = (api, config) => {
 	writer.line("import okhttp3.*");
 	writer.line("import okhttp3.MediaType.Companion.toMediaType");
 	writer.line("import okhttp3.RequestBody.Companion.toRequestBody");
+	writer.line("import kotlin.time.Duration.Companion.milliseconds");
+	writer.line("import kotlin.time.Duration.Companion.seconds");
 	writer.line("import okhttp3.HttpUrl.Companion.toHttpUrl");
 	writer.blank();
 	if (registry.all().some((type) => type.kind === "enum-class")) {
@@ -1784,13 +1897,43 @@ const generateKotlinClient = (api, config) => {
 	};
 	writer.block(`object ${namespaceName}`, () => {
 		emitTypes(writer, topLevelSharedTypes, ownedTypeMap, ownedTypeLookup, registry);
+		for (const brand of registry.allBrands()) {
+			writer.blank();
+			emitBrand(writer, brand);
+		}
 	});
 	emitClient(writer, { clientName }, partition, context, typesByOperation, registry);
 	for (const group of partition.groups) emitSubClientClass(writer, group, clientName, context);
-	emitKizunaObject(writer, { streaming: usesStreaming });
+	emitKizunaObject(writer, {
+		streaming: usesStreaming,
+		clientName
+	});
 	for (const warning of registry.warnings()) process.stderr.write(`[kizuna/kotlin] JsonElement fallback at ${warning}\n`);
 	return writer.toString();
 };
+/**
+* The Kotlin client's walk: the routes into a partition, then the file.
+*/
+const kotlinClientWalk = (api, config) => {
+	const registry = new TypeRegistry(config.camelCaseProperties ?? false, config.unknownEnumCase ?? false);
+	const routes = kotlinRoutesWalk({
+		namespaceName: config.namespaceName,
+		registry
+	});
+	return {
+		processRoute: routes.processRoute,
+		finalize: () => renderKotlinClient(api, routes.finalize(), registry, config)
+	};
+};
+/**
+* Generate a Kotlin API client from a Kizuna api.
+*
+* @param api - What `defineConfig` assembled.
+* @param config - Override the generated names:
+*   - `namespaceName`: the object wrapping shared types.
+*   - `packageName`: optional package declaration for the generated file.
+*/
+const generateKotlinClient = (api, config) => (0, kizunajs_generator.walkApi)(api, kotlinClientWalk(api, config), { skipHidden: true });
 //#endregion
 Object.defineProperty(exports, "generateKotlinClient", {
 	enumerable: true,
@@ -1798,3 +1941,9 @@ Object.defineProperty(exports, "generateKotlinClient", {
 		return generateKotlinClient;
 	}
 });
+Object.defineProperty(exports, "kotlinClientWalk", {
+	enumerable: true,
+	get: function() {
+		return kotlinClientWalk;
+	}
+});

package/dist/{generator-BvNpSarY.mjs → generator-D4GvH1-a.mjs}

@@ -1,4 +1,4 @@
-import { createGenerator, isDiscriminatedUnionSchema, isFileSchema, isHintPrefix, isIntegerSchema, isNamedStream, isObjectSchema, isStreamResponse, isSuccessStatus, localTypeName, mergeHeaderFields, parsePath, readDef, readDefType, readDeprecation, readDiscriminatedUnion, readDiscriminatorStringLiteral, readMetaDescription, readMetaId, readObjectShape, resolveResponseBody, resolveResponseHeaders, routeStreams, sanitizeFieldName, sanitizeIdentifier, shortTypeName, soleStreamResponse, statusToCamelCase, streamMode, toCamelCase, toPascalCase, unwrapOptionalWrappers } from "kizunajs/generator";
+import { isBinarySchema, isDiscriminatedUnionSchema, isFileSchema, isHintPrefix, isIntegerSchema, isNamedStream, isObjectSchema, isStreamResponse, isSuccessStatus, localTypeName, mergeHeaderFields, parsePath, readDef, readDefType, readDeprecation, readDiscriminatedUnion, readDiscriminatorStringLiteral, readMetaBrand, readMetaDescription, readMetaId, readObjectShape, resolveResponseBody, resolveResponseHeaders, routeStreams, sanitizeFieldName, sanitizeIdentifier, shortTypeName, soleStreamResponse, statusToCamelCase, streamMode, toCamelCase, toPascalCase, unwrapOptionalWrappers, walkApi } from "kizunajs/generator";
 //#region src/emit.ts
 var KotlinWriter = class {
 	lines = [];
@@ -56,6 +56,7 @@ var TypeRegistry = class {
 	explicitIds = /* @__PURE__ */ new Set();
 	sealedVariantPayloads = /* @__PURE__ */ new Set();
 	sealedVariantPaths = /* @__PURE__ */ new Map();
+	brands = /* @__PURE__ */ new Map();
 	usesJsonElement = false;
 	constructor(camelCaseProperties = false, unknownEnumCase = false) {
 		this.camelCaseProperties = camelCaseProperties;
@@ -99,6 +100,15 @@ var TypeRegistry = class {
 	sealedVariantPath(name) {
 		return this.sealedVariantPaths.get(name);
 	}
+	addBrand(brand) {
+		const existing = this.brands.get(brand.name);
+		if (existing !== void 0 && existing.rawType !== brand.rawType) throw new Error(`@kizunajs/kotlin: brand ${stringify(brand.name)} wraps both ${existing.rawType} and ${brand.rawType}. Give each its own name.`);
+		if (this.types.has(brand.name)) throw new Error(`@kizunajs/kotlin: brand ${stringify(brand.name)} has the same name as a model. Give each its own name.`);
+		this.brands.set(brand.name, brand);
+	}
+	allBrands() {
+		return Array.from(this.brands.values());
+	}
 	warnJsonElement(hint, reason) {
 		this.usesJsonElement = true;
 		this.warningSet.add(`${hint}: ${reason}`);
@@ -117,8 +127,7 @@ const propertyName = (key, camelCase) => {
 	if (!camel) return "field";
 	return /^[0-9]/.test(camel) ? `_${camel}` : camel;
 };
-const objectFields = (schema, registry, hint) => {
-	const shape = readObjectShape(schema) ?? {};
+const objectFields = (schema, registry, hint, shape = readObjectShape(schema) ?? {}) => {
 	const fields = [];
 	const seen = /* @__PURE__ */ new Map();
 	for (const [key, value] of Object.entries(shape)) {
@@ -133,6 +142,7 @@ const objectFields = (schema, registry, hint) => {
 			wireName: key,
 			type: result.expression,
 			optional: result.optional,
+			requiredNullable: result.requiredNullable,
 			description: readMetaDescription(value),
 			isFile: result.isFile,
 			deprecated: deprecation !== void 0,
@@ -142,12 +152,38 @@ const objectFields = (schema, registry, hint) => {
 	return fields;
 };
 const stringify = (value) => JSON.stringify(value);
+const BRANDABLE_TYPES = new Set([
+	"String",
+	"Int",
+	"Long",
+	"Double",
+	"Boolean",
+	"Instant"
+]);
 const mapType = (schema, registry, hint) => {
+	const result = mapUnbrandedType(schema, registry, hint);
+	const brand = readMetaBrand(schema);
+	if (brand === void 0 || !BRANDABLE_TYPES.has(result.expression)) return result;
+	const name = sanitizeIdentifier(brand);
+	registry.addBrand({
+		name,
+		rawType: result.expression
+	});
+	return {
+		expression: name,
+		optional: false
+	};
+};
+const mapUnbrandedType = (schema, registry, hint) => {
 	if (isFileSchema(schema)) return {
 		expression: "MultipartFile",
 		optional: false,
 		isFile: true
 	};
+	if (isBinarySchema(schema)) return {
+		expression: "ByteArray",
+		optional: false
+	};
 	const id = readMetaId(schema);
 	const def = readDef(schema);
 	const discriminated = readDiscriminatedUnion(schema);
@@ -223,12 +259,13 @@ const mapType = (schema, registry, hint) => {
 			optional: false
 		};
 	}
-	const { inner, optional } = unwrapOptionalWrappers(schema);
-	if (optional) {
+	const { inner, optional, nullable } = unwrapOptionalWrappers(schema);
+	if (optional || nullable) {
 		const innerResult = mapType(inner, registry, hint);
 		return {
 			expression: innerResult.expression.endsWith("?") ? innerResult.expression : `${innerResult.expression}?`,
 			optional: true,
+			requiredNullable: nullable && !optional,
 			isFile: innerResult.isFile
 		};
 	}
@@ -277,8 +314,9 @@ const mapType = (schema, registry, hint) => {
 					optional: false
 				};
 			}
+			const elementType = mapType(element, registry, `${hint}Item`).expression.replace(/\?$/, "");
 			return {
-				expression: `List<${mapType(element, registry, `${hint}Item`).expression.replace(/\?$/, "")}>`,
+				expression: `List<${unwrapOptionalWrappers(element).nullable ? `${elementType}?` : elementType}>`,
 				optional: false
 			};
 		}
@@ -412,6 +450,7 @@ const sanitizeCaseName = (literal) => {
 const collectObjectFields = (schema, registry, hint) => {
 	return objectFields(schema, registry, hint);
 };
+const hasDefault = (field) => field.optional && field.requiredNullable !== true;
 const objectFieldCount = (schema) => {
 	return Object.keys(readObjectShape(schema) ?? {}).length;
 };
@@ -576,7 +615,7 @@ const buildRouteMethod = (routeKey, route, registry, deprecated, deprecationMess
 		stream
 	};
 };
-const kotlinGenerator = createGenerator((options, _api) => {
+const kotlinRoutesWalk = (options) => {
 	const flatMethods = [];
 	const groupMap = /* @__PURE__ */ new Map();
 	return {
@@ -608,7 +647,7 @@ const kotlinGenerator = createGenerator((options, _api) => {
 			};
 		}
 	};
-});
+};
 const KOTLIN_KEYWORDS = new Set([
 	"as",
 	"break",
@@ -642,6 +681,10 @@ const KOTLIN_KEYWORDS = new Set([
 const escapeKeyword = (name) => {
 	return KOTLIN_KEYWORDS.has(name) ? `\`${name}\`` : name;
 };
+const defaultArgument = (field) => {
+	if (!hasDefault(field)) return "";
+	return " = null";
+};
 const optionalize = (type, optional) => {
 	if (!optional) return type;
 	return type.endsWith("?") ? type : `${type}?`;
@@ -653,8 +696,13 @@ const KOTLIN_PRIMITIVE_TYPES = new Set([
 	"Long",
 	"Boolean",
 	"Instant",
-	"Unit"
+	"Unit",
+	"ByteArray"
 ]);
+/**
+* How a response body is read. Raw bytes are the body already.
+*/
+const decodeBody = (resolved) => resolved === "ByteArray" ? "data" : `json.decodeFromString<${resolved}>(data.decodeToString())`;
 const resolveType = (typeName, currentOperation, context, scope = "client") => {
 	const { operationTypeMap, namespaceName, clientName, fileLevelTypeNames } = context;
 	const optional = typeName.endsWith("?");
@@ -797,7 +845,7 @@ const emitDataClass = (writer, type, ownedTypeMap, ownedTypeLookup, registryName
 	if (!hasFile) writer.line("@Serializable");
 	const params = adjustedFields.map((field) => {
 		const typeExpression = optionalize(field.type, field.optional);
-		const defaultPart = field.optional ? " = null" : "";
+		const defaultPart = defaultArgument(field);
 		const serialNameAnnotation = needsSerialName && (field.name !== field.wireName || KOTLIN_KEYWORDS.has(field.name)) ? `@SerialName(${stringLiteral(field.wireName)}) ` : "";
 		return `${field.deprecated ? `${deprecatedAnnotation(field.deprecationMessage)} ` : ""}${serialNameAnnotation}val ${escapeKeyword(field.name)}: ${typeExpression}${defaultPart}`;
 	});
@@ -890,7 +938,7 @@ const emitSealedClass = (writer, type, registry, ownedTypeMap, ownedTypeLookup)
 					const params = fields.map((field) => {
 						const variantPath = registry.sealedVariantPath(variant.payloadType) ?? variant.payloadType;
 						const typeExpression = optionalize(relativeOwnedPath(field.type, ownedTypeMap, variantPath, registry) ?? ownedTypePath(field.type, ownedTypeMap, registry), field.optional);
-						const defaultPart = field.optional ? " = null" : "";
+						const defaultPart = defaultArgument(field);
 						return `val ${escapeKeyword(field.name)}: ${typeExpression}${defaultPart}`;
 					});
 					if (params.length === 1) writer.line(`data class ${variant.caseName}(${params[0]}) : ${type.name}`);
@@ -927,6 +975,16 @@ const emitType = (writer, type, ownedTypeMap = /* @__PURE__ */ new Map(), ownedT
 	else if (type.kind === "enum-class") emitEnumClass(writer, type.name, type.cases, type.unknownCase, type.description);
 	else if (registry) emitSealedClass(writer, type, registry, ownedTypeMap, ownedTypeLookup);
 };
+/**
+* A brand as a value class that serializes and prints as the bare value.
+*/
+const emitBrand = (writer, brand) => {
+	writer.line("@Serializable");
+	writer.line("@JvmInline");
+	writer.block(`value class ${brand.name}(val value: ${brand.rawType})`, () => {
+		writer.line(`override fun toString(): String = ${brand.rawType === "String" ? "value" : "value.toString()"}`);
+	});
+};
 const emitTypes = (writer, types, ownedTypeMap = /* @__PURE__ */ new Map(), ownedTypeLookup = /* @__PURE__ */ new Map(), registry) => {
 	for (const type of types) emitType(writer, type, ownedTypeMap, ownedTypeLookup, void 0, registry);
 };
@@ -1002,7 +1060,7 @@ const emitOperationResultTypes = (writer, method, context) => {
 			writer.line(") {");
 			writer.indent(() => {
 				writer.line("/** How far along the call is. */");
-				writer.line("enum class State { Running, Done, Failed }");
+				writer.line("enum class State { Running, NeedsApproval, Done, Failed }");
 			});
 			writer.line("}");
 			writer.blank();
@@ -1012,7 +1070,12 @@ const emitOperationResultTypes = (writer, method, context) => {
 				writer.block("for (event in events)", () => {
 					writer.line("when (event) {");
 					writer.indent(() => {
-						writer.line("is Event.ToolCall -> calls[event.data.id] = (calls[event.data.id] ?: ToolCallRecord(event.data.id, event.data.name)).copy(call = event.data)");
+						writer.line("is Event.ToolCall -> {");
+						writer.indent(() => {
+							writer.line("val tracked = (calls[event.data.id] ?: ToolCallRecord(event.data.id, event.data.name)).copy(call = event.data)");
+							writer.line("calls[event.data.id] = if (event.data.needsApproval == true && tracked.state == ToolCallRecord.State.Running) tracked.copy(state = ToolCallRecord.State.NeedsApproval) else tracked");
+						});
+						writer.line("}");
 						writer.line("is Event.ToolResult -> calls[event.data.id] = (calls[event.data.id] ?: ToolCallRecord(event.data.id, event.data.name)).copy(state = ToolCallRecord.State.Done, result = event.data)");
 						if (eventNames.has("tool_error")) writer.line("is Event.ToolError -> calls[event.data.id] = (calls[event.data.id] ?: ToolCallRecord(event.data.id, event.data.name.wireValue)).copy(state = ToolCallRecord.State.Failed, message = event.data.message)");
 						writer.line("else -> Unit");
@@ -1074,7 +1137,7 @@ const groupTypeRef = (operationName, className, context) => `${context.clientNam
 const groupMemberAccessor = (groupLabel, field) => `${groupLabel}.${escapeKeyword(field.name)}`;
 const groupClassField = (field) => {
 	const typeExpression = optionalize(field.type, field.optional);
-	const defaultPart = field.optional ? " = null" : "";
+	const defaultPart = defaultArgument(field);
 	return `val ${escapeKeyword(field.name)}: ${typeExpression}${defaultPart}`;
 };
 const emitGroupClass = (writer, className, fields, method, context) => {
@@ -1133,13 +1196,13 @@ const methodChannels = (method) => {
 	if (method.query.length > 0) channels.push({
 		varName: "query",
 		className: "Query",
-		required: method.query.some((field) => !field.optional),
+		required: method.query.some((field) => !hasDefault(field)),
 		fields: method.query
 	});
 	if (method.headers.length > 0) channels.push({
 		varName: "headers",
 		className: "Headers",
-		required: method.headers.some((field) => !field.optional),
+		required: method.headers.some((field) => !hasDefault(field)),
 		fields: method.headers
 	});
 	if (hasBodyGroup(method)) {
@@ -1188,7 +1251,7 @@ const emitArgsScaffolding = (writer, method, context) => {
 	};
 	const factorySignature = (channel) => channel.fields.map((field) => {
 		const typeExpression = optionalize(field.type, field.optional);
-		const defaultPart = field.optional ? " = null" : "";
+		const defaultPart = defaultArgument(field);
 		return `${escapeKeyword(field.name)}: ${typeExpression}${defaultPart}`;
 	}).join(", ");
 	const factoryConstruction = (channel) => {
@@ -1245,10 +1308,16 @@ const emitBodyEncoding = (writer, method, context) => {
 	if (body.kind === "multipart") {
 		writer.line("val multipartBuilder = MultipartBody.Builder().setType(MultipartBody.FORM)");
 		for (const field of body.multipartFields) {
-			const accessor = groupMemberAccessor("body", field);
-			const isFlattenedFile = body.flattened.find((flatField) => flatField.name === field.name)?.isFile === true;
-			if (field.isFile || isFlattenedFile) writer.line(`multipartBuilder.addFormDataPart(${stringLiteral(field.wireName)}, ${accessor}.filename, ${accessor}.data.toRequestBody(${accessor}.mimeType.toMediaType()))`);
-			else writer.line(`multipartBuilder.addFormDataPart(${stringLiteral(field.wireName)}, ${accessor}.toString())`);
+			const flattenedField = body.flattened.find((flatField) => flatField.name === field.name);
+			const isFile = field.isFile || flattenedField?.isFile === true;
+			const append = (accessor) => {
+				if (isFile) writer.line(`multipartBuilder.addFormDataPart(${stringLiteral(field.wireName)}, ${accessor}.filename, ${accessor}.data.toRequestBody(${accessor}.mimeType.toMediaType()))`);
+				else writer.line(`multipartBuilder.addFormDataPart(${stringLiteral(field.wireName)}, ${accessor}.toString())`);
+			};
+			if (flattenedField?.optional === true) writer.block(`if (${groupMemberAccessor("body", field)} != null)`, () => {
+				append(groupMemberAccessor("body", field));
+			});
+			else append(groupMemberAccessor("body", field));
 		}
 		writer.line("requestBody = multipartBuilder.build()");
 		return;
@@ -1324,7 +1393,7 @@ const emitMethodBody = (writer, method, context) => {
 		else setHeader(accessor);
 	}
 	writer.line("requestInterceptor?.invoke(requestBuilder)");
-	writer.line("val httpResponse = Kizuna.execute(client, requestBuilder.build())");
+	writer.line("val httpResponse = Kizuna.send(client, requestBuilder.build(), retry)");
 	if (method.stream) {
 		emitStreamMethodTail(writer, method, context);
 		return;
@@ -1344,7 +1413,7 @@ const emitMethodBody = (writer, method, context) => {
 				writer.indent(() => {
 					const resolved = resolveType(successResponse.type, method.operationName, context);
 					writer.block("try", () => {
-						writer.line(`val payload = json.decodeFromString<${resolved}>(data.decodeToString())`);
+						writer.line(`val payload = ${decodeBody(resolved)}`);
 						const bodyExpr = isMultiSuccess ? `${operationRef}.Success.Status${successResponse.status}(payload)` : "payload";
 						if (hasHeaders) {
 							for (const field of successResponse.responseHeaders) writer.line(`val ${escapeKeyword(field.name)} = httpResponse.header(${stringLiteral(field.wireName)})`);
@@ -1381,7 +1450,7 @@ const emitErrorBranches = (writer, method, context) => {
 					const resolved = resolveType(errorCase.type, method.operationName, context);
 					writer.line("val payload = try {");
 					writer.indent(() => {
-						writer.line(`json.decodeFromString<${resolved}>(data.decodeToString())`);
+						writer.line(decodeBody(resolved));
 					});
 					writer.line(`} catch (error: Exception) { throw ${failureRef}.Decoding(error, statusCode, data) }`);
 					writer.line(`throw ${failureRef}.${caseName}(body = payload)`);
@@ -1394,7 +1463,7 @@ const emitErrorBranches = (writer, method, context) => {
 						const resolved = resolveType(errorCase.type, method.operationName, context);
 						writer.line(`val ${errorCase.caseName} = try {`);
 						writer.indent(() => {
-							writer.line(`json.decodeFromString<${resolved}>(data.decodeToString())`);
+							writer.line(decodeBody(resolved));
 						});
 						writer.line("} catch (_: Exception) { null }");
 						writer.line(`if (${errorCase.caseName} != null) throw ${failureRef}.${caseName}(body = ${errorCase.caseName})`);
@@ -1476,7 +1545,7 @@ const emitSubClientMethod = (writer, method, context) => {
 };
 const emitSubClientClass = (writer, group, clientName, context) => {
 	writer.blank();
-	writer.block(`class ${group.className}(private val client: OkHttpClient, private val baseUrl: String, private val json: Json, private val requestContextHeaders: Map<String, String>, private val requestInterceptor: (suspend (Request.Builder) -> Unit)?, private val responseInterceptor: (suspend (Request, Response) -> Unit)?)`, () => {
+	writer.block(`class ${group.className}(private val client: OkHttpClient, private val baseUrl: String, private val json: Json, private val requestContextHeaders: Map<String, String>, private val requestInterceptor: (suspend (Request.Builder) -> Unit)?, private val responseInterceptor: (suspend (Request, Response) -> Unit)?, private val retry: ${clientName}.RetryPolicy?)`, () => {
 		for (const method of group.methods) {
 			writer.blank();
 			emitSubClientMethod(writer, method, context);
@@ -1581,6 +1650,47 @@ const emitKizunaObject = (writer, options) => {
 			writer.line("}");
 		});
 		writer.blank();
+		writer.block(`suspend fun send(client: OkHttpClient, request: Request, retry: ${options.clientName}.RetryPolicy?): Response`, () => {
+			writer.line("val idempotent = request.method in setOf(\"GET\", \"HEAD\", \"OPTIONS\", \"PUT\", \"DELETE\")");
+			writer.line("val policy = retry?.takeIf { idempotent && request.body?.isOneShot() != true }");
+			writer.line("var attempt = 1");
+			writer.block("while (true)", () => {
+				writer.line("val response = try {");
+				writer.line("    execute(client, request)");
+				writer.line("} catch (error: java.io.IOException) {");
+				writer.line("    val delay = policy?.let { retryDelay(it, attempt, null) } ?: throw error");
+				writer.line("    kotlinx.coroutines.delay(delay)");
+				writer.line("    attempt += 1");
+				writer.line("    continue");
+				writer.line("}");
+				writer.line("val delay = policy?.let { retryDelay(it, attempt, response) } ?: return response");
+				writer.line("response.close()");
+				writer.line("kotlinx.coroutines.delay(delay)");
+				writer.line("attempt += 1");
+			});
+		});
+		writer.blank();
+		writer.block(`fun retryDelay(policy: ${options.clientName}.RetryPolicy, attempt: Int, response: Response?): Long?`, () => {
+			writer.line("if (attempt >= policy.maximumAttempts) return null");
+			writer.line("val ceiling = minOf(policy.maximumDelay.inWholeMilliseconds, policy.initialDelay.inWholeMilliseconds shl (attempt - 1))");
+			writer.line("val backoff = (Math.random() * ceiling).toLong()");
+			writer.line("if (response == null) return backoff");
+			writer.line("if (response.code != 429 && response.code != 503) return null");
+			writer.line("val asked = retryAfter(response.header(\"Retry-After\")) ?: return backoff");
+			writer.line("return if (asked <= policy.maximumDelay.inWholeMilliseconds) asked else null");
+		});
+		writer.blank();
+		writer.block("fun retryAfter(header: String?): Long?", () => {
+			writer.line("val value = header?.trim() ?: return null");
+			writer.line("value.toLongOrNull()?.let { return if (it >= 0) it * 1000 else null }");
+			writer.line("val date = try {");
+			writer.line("    java.time.ZonedDateTime.parse(value, java.time.format.DateTimeFormatter.RFC_1123_DATE_TIME)");
+			writer.line("} catch (_: java.time.format.DateTimeParseException) {");
+			writer.line("    return null");
+			writer.line("}");
+			writer.line("return maxOf(0L, date.toInstant().toEpochMilli() - System.currentTimeMillis())");
+		});
+		writer.blank();
 		writer.block("suspend fun execute(client: OkHttpClient, request: Request): Response", () => {
 			writer.line("return kotlinx.coroutines.suspendCancellableCoroutine { continuation ->");
 			writer.indent(() => {
@@ -1608,20 +1718,34 @@ const emitClient = (writer, config, partition, context, typesByOperation, regist
 	const allMethods = [...flatMethods, ...groups.flatMap((group) => group.methods)];
 	const usesMultipart = allMethods.some((method) => method.body?.kind === "multipart");
 	const contextFields = context.requestContextFields;
-	const contextRequired = contextFields.some((field) => !field.optional);
+	const contextRequired = contextFields.some((field) => !hasDefault(field));
 	const contextParam = contextFields.length > 0 ? `requestContext: RequestContext${contextRequired ? "" : " = RequestContext()"}, ` : "";
 	writer.blank();
-	writer.block(`class ${clientName}(private val baseUrl: String, ${contextParam}private val client: OkHttpClient = OkHttpClient(), private val json: Json = Json { ignoreUnknownKeys = true }, private val requestInterceptor: (suspend (Request.Builder) -> Unit)? = null, private val responseInterceptor: (suspend (Request, Response) -> Unit)? = null)`, () => {
+	writer.block(`class ${clientName}(private val baseUrl: String, ${contextParam}private val client: OkHttpClient = OkHttpClient(), private val json: Json = Json { ignoreUnknownKeys = true }, private val requestInterceptor: (suspend (Request.Builder) -> Unit)? = null, private val responseInterceptor: (suspend (Request, Response) -> Unit)? = null, private val retry: RetryPolicy? = null)`, () => {
 		if (contextFields.length > 0) {
 			writer.blank();
 			writer.line("/** Values sent as headers on every request, from the api's request context. */");
-			emitConstructorClass(writer, "data class RequestContext", contextFields.map((field) => `val ${escapeKeyword(field.name)}: ${field.type}${field.optional ? " = null" : ""}`));
+			emitConstructorClass(writer, "data class RequestContext", contextFields.map((field) => `val ${escapeKeyword(field.name)}: ${field.type}${defaultArgument(field)}`));
 			writer.blank();
 			writer.block("private val requestContextHeaders: Map<String, String> = buildMap", () => {
 				for (const field of contextFields) if (field.optional) writer.line(`if (requestContext.${escapeKeyword(field.name)} != null) put(${stringLiteral(field.wireName)}, requestContext.${escapeKeyword(field.name)}!!)`);
 				else writer.line(`put(${stringLiteral(field.wireName)}, requestContext.${escapeKeyword(field.name)})`);
 			});
 		}
+		writer.blank();
+		writer.line("/**");
+		writer.line(" * Retries a GET, HEAD, OPTIONS, PUT or DELETE that failed on the network or was answered 429 or 503,");
+		writer.line(" * waiting what Retry-After asks or backing off.");
+		writer.line(" *");
+		writer.line(" * @property maximumAttempts Attempts in all, the first included.");
+		writer.line(" * @property initialDelay What the first backoff waits at most.");
+		writer.line(" * @property maximumDelay What any wait may take.");
+		writer.line(" */");
+		emitConstructorClass(writer, "data class RetryPolicy", [
+			"val maximumAttempts: Int = 3",
+			"val initialDelay: kotlin.time.Duration = 500.milliseconds",
+			"val maximumDelay: kotlin.time.Duration = 30.seconds"
+		]);
 		if (usesMultipart) {
 			writer.blank();
 			emitConstructorClass(writer, "data class MultipartFile", [
@@ -1677,7 +1801,7 @@ const emitClient = (writer, config, partition, context, typesByOperation, regist
 		}
 		if (groups.length > 0) for (const group of groups) {
 			writer.blank();
-			writer.line(`val ${escapeKeyword(group.propertyName)} = ${group.className}(client, baseUrl, json, ${contextFields.length > 0 ? "requestContextHeaders" : "emptyMap()"}, requestInterceptor, responseInterceptor)`);
+			writer.line(`val ${escapeKeyword(group.propertyName)} = ${group.className}(client, baseUrl, json, ${contextFields.length > 0 ? "requestContextHeaders" : "emptyMap()"}, requestInterceptor, responseInterceptor, retry)`);
 		}
 		for (const method of flatMethods) {
 			writer.blank();
@@ -1685,21 +1809,8 @@ const emitClient = (writer, config, partition, context, typesByOperation, regist
 		}
 	});
 };
-/**
-* Generate a Kotlin API client from a Kizuna api.
-*
-* @param api - What `defineConfig` assembled.
-* @param config - Override the generated names:
-*   - `namespaceName`: the object wrapping shared types.
-*   - `packageName`: optional package declaration for the generated file.
-*/
-const generateKotlinClient = (api, config) => {
-	const { namespaceName, packageName, camelCaseProperties = false, unknownEnumCase = false } = config;
-	const registry = new TypeRegistry(camelCaseProperties, unknownEnumCase);
-	const partition = kotlinGenerator(api, {
-		namespaceName,
-		registry
-	});
+const renderKotlinClient = (api, partition, registry, config) => {
+	const { namespaceName, packageName, camelCaseProperties = false } = config;
 	const allMethods = [...partition.flatMethods, ...partition.groups.flatMap((group) => group.methods)];
 	const operationTypeMap = buildOperationTypeMap(allMethods, registry);
 	const clientName = `${namespaceName}Client`;
@@ -1735,6 +1846,8 @@ const generateKotlinClient = (api, config) => {
 	writer.line("import okhttp3.*");
 	writer.line("import okhttp3.MediaType.Companion.toMediaType");
 	writer.line("import okhttp3.RequestBody.Companion.toRequestBody");
+	writer.line("import kotlin.time.Duration.Companion.milliseconds");
+	writer.line("import kotlin.time.Duration.Companion.seconds");
 	writer.line("import okhttp3.HttpUrl.Companion.toHttpUrl");
 	writer.blank();
 	if (registry.all().some((type) => type.kind === "enum-class")) {
@@ -1784,12 +1897,42 @@ const generateKotlinClient = (api, config) => {
 	};
 	writer.block(`object ${namespaceName}`, () => {
 		emitTypes(writer, topLevelSharedTypes, ownedTypeMap, ownedTypeLookup, registry);
+		for (const brand of registry.allBrands()) {
+			writer.blank();
+			emitBrand(writer, brand);
+		}
 	});
 	emitClient(writer, { clientName }, partition, context, typesByOperation, registry);
 	for (const group of partition.groups) emitSubClientClass(writer, group, clientName, context);
-	emitKizunaObject(writer, { streaming: usesStreaming });
+	emitKizunaObject(writer, {
+		streaming: usesStreaming,
+		clientName
+	});
 	for (const warning of registry.warnings()) process.stderr.write(`[kizuna/kotlin] JsonElement fallback at ${warning}\n`);
 	return writer.toString();
 };
+/**
+* The Kotlin client's walk: the routes into a partition, then the file.
+*/
+const kotlinClientWalk = (api, config) => {
+	const registry = new TypeRegistry(config.camelCaseProperties ?? false, config.unknownEnumCase ?? false);
+	const routes = kotlinRoutesWalk({
+		namespaceName: config.namespaceName,
+		registry
+	});
+	return {
+		processRoute: routes.processRoute,
+		finalize: () => renderKotlinClient(api, routes.finalize(), registry, config)
+	};
+};
+/**
+* Generate a Kotlin API client from a Kizuna api.
+*
+* @param api - What `defineConfig` assembled.
+* @param config - Override the generated names:
+*   - `namespaceName`: the object wrapping shared types.
+*   - `packageName`: optional package declaration for the generated file.
+*/
+const generateKotlinClient = (api, config) => walkApi(api, kotlinClientWalk(api, config), { skipHidden: true });
 //#endregion
-export { generateKotlinClient as t };
+export { kotlinClientWalk as n, generateKotlinClient as t };

package/dist/index.cjs

@@ -1,17 +1,48 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_generator = require("./generator-s2pn7vqP.cjs");
+const require_generator = require("./generator-Bg4HlRb3.cjs");
+let kizunajs_generator = require("kizunajs/generator");
+let zod = require("zod");
 //#region src/client-target.ts
+const KotlinClientOptionsSchema = zod.z.object({
+	/**
+	* Name of the generated namespace object.
+	*
+	* @default 'API'
+	*/
+	namespace: zod.z.string().default("API"),
+	/**
+	* Package declaration for the generated file, e.g. `com.example.api`.
+	*/
+	package: zod.z.string().optional(),
+	/**
+	* Convert wire field names to camelCase properties, mapping the wire name
+	* back via `@SerialName`.
+	*
+	* @default false
+	*/
+	camelCaseProperties: zod.z.boolean().optional(),
+	/**
+	* Give every enum an `unknown` case, so a value the client has not been
+	* generated for decodes instead of throwing.
+	*
+	* @default false
+	*/
+	unknownEnumCase: zod.z.boolean().optional()
+});
 /**
-* A Kotlin client target for `kizuna.config.ts`.
+* A Kotlin client for `kizuna.config.ts`.
 *
 * @example
-* kotlinClient({ output: './api/APIClient.kt', package: 'com.example.api' });
+* kotlinClient({
+*     output: './api/APIClient.kt',
+*     package: 'com.example.api',
+* });
 */
-const kotlinClient = (options) => ({
-	kind: "kotlin",
-	output: options.output,
-	generate: (contract) => require_generator.generateKotlinClient(contract, {
-		namespaceName: options.namespace ?? "API",
+const kotlinClient = (0, kizunajs_generator.defineClient)({
+	target: "kotlin",
+	options: KotlinClientOptionsSchema,
+	generate: ({ options, api }) => require_generator.kotlinClientWalk(api, {
+		namespaceName: options.namespace,
 		packageName: options.package,
 		camelCaseProperties: options.camelCaseProperties,
 		unknownEnumCase: options.unknownEnumCase

package/dist/index.d.cts

@@ -1,4 +1,7 @@
-import { ApiDefinition, ClientTarget } from "kizunajs";
+import { GeneratedFileOptions } from "kizunajs/generator";
+import * as _$kizunajs from "kizunajs";
+import { ApiDefinition } from "kizunajs";
+import { z } from "zod";
 
 //#region src/generator.d.ts
 interface KotlinConfig {
@@ -38,45 +41,30 @@ interface KotlinConfig {
 declare const generateKotlinClient: (api: ApiDefinition, config: KotlinConfig) => string;
 //#endregion
 //#region src/client-target.d.ts
+declare const KotlinClientOptionsSchema: z.ZodObject<{
+  namespace: z.ZodDefault<z.ZodString>;
+  package: z.ZodOptional<z.ZodString>;
+  camelCaseProperties: z.ZodOptional<z.ZodBoolean>;
+  unknownEnumCase: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
 /**
  * Where a generated Kotlin client is written, and what it is called there.
  */
-interface KotlinClientOptions {
-  /**
-   * Path the generated file is written to.
-   */
-  output: string;
-  /**
-   * Name of the generated namespace object.
-   *
-   * @default 'API'
-   */
-  namespace?: string;
-  /**
-   * Package declaration for the generated file, e.g. `com.example.api`.
-   */
-  package?: string;
-  /**
-   * Convert wire field names to camelCase properties, mapping the wire name
-   * back via `@SerialName`.
-   *
-   * @default false
-   */
-  camelCaseProperties?: boolean;
-  /**
-   * Give every enum an `unknown` case, so a value the client has not been
-   * generated for decodes instead of throwing.
-   *
-   * @default false
-   */
-  unknownEnumCase?: boolean;
-}
+type KotlinClientOptions = z.input<typeof KotlinClientOptionsSchema> & GeneratedFileOptions;
 /**
- * A Kotlin client target for `kizuna.config.ts`.
+ * A Kotlin client for `kizuna.config.ts`.
  *
  * @example
- * kotlinClient({ output: './api/APIClient.kt', package: 'com.example.api' });
+ * kotlinClient({
+ *     output: './api/APIClient.kt',
+ *     package: 'com.example.api',
+ * });
  */
-declare const kotlinClient: (options: KotlinClientOptions) => ClientTarget;
+declare const kotlinClient: (options: {
+  namespace?: string | undefined;
+  package?: string | undefined;
+  camelCaseProperties?: boolean | undefined;
+  unknownEnumCase?: boolean | undefined;
+} & GeneratedFileOptions) => _$kizunajs.GeneratedFile;
 //#endregion
 export { type KotlinClientOptions, type KotlinConfig, generateKotlinClient, kotlinClient };

package/dist/index.d.mts

@@ -1,4 +1,7 @@
-import { ApiDefinition, ClientTarget } from "kizunajs";
+import { GeneratedFileOptions } from "kizunajs/generator";
+import { z } from "zod";
+import * as _$kizunajs from "kizunajs";
+import { ApiDefinition } from "kizunajs";
 
 //#region src/generator.d.ts
 interface KotlinConfig {
@@ -38,45 +41,30 @@ interface KotlinConfig {
 declare const generateKotlinClient: (api: ApiDefinition, config: KotlinConfig) => string;
 //#endregion
 //#region src/client-target.d.ts
+declare const KotlinClientOptionsSchema: z.ZodObject<{
+  namespace: z.ZodDefault<z.ZodString>;
+  package: z.ZodOptional<z.ZodString>;
+  camelCaseProperties: z.ZodOptional<z.ZodBoolean>;
+  unknownEnumCase: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
 /**
  * Where a generated Kotlin client is written, and what it is called there.
  */
-interface KotlinClientOptions {
-  /**
-   * Path the generated file is written to.
-   */
-  output: string;
-  /**
-   * Name of the generated namespace object.
-   *
-   * @default 'API'
-   */
-  namespace?: string;
-  /**
-   * Package declaration for the generated file, e.g. `com.example.api`.
-   */
-  package?: string;
-  /**
-   * Convert wire field names to camelCase properties, mapping the wire name
-   * back via `@SerialName`.
-   *
-   * @default false
-   */
-  camelCaseProperties?: boolean;
-  /**
-   * Give every enum an `unknown` case, so a value the client has not been
-   * generated for decodes instead of throwing.
-   *
-   * @default false
-   */
-  unknownEnumCase?: boolean;
-}
+type KotlinClientOptions = z.input<typeof KotlinClientOptionsSchema> & GeneratedFileOptions;
 /**
- * A Kotlin client target for `kizuna.config.ts`.
+ * A Kotlin client for `kizuna.config.ts`.
  *
  * @example
- * kotlinClient({ output: './api/APIClient.kt', package: 'com.example.api' });
+ * kotlinClient({
+ *     output: './api/APIClient.kt',
+ *     package: 'com.example.api',
+ * });
  */
-declare const kotlinClient: (options: KotlinClientOptions) => ClientTarget;
+declare const kotlinClient: (options: {
+  namespace?: string | undefined;
+  package?: string | undefined;
+  camelCaseProperties?: boolean | undefined;
+  unknownEnumCase?: boolean | undefined;
+} & GeneratedFileOptions) => _$kizunajs.GeneratedFile;
 //#endregion
 export { type KotlinClientOptions, type KotlinConfig, generateKotlinClient, kotlinClient };

package/dist/index.mjs

@@ -1,16 +1,45 @@
-import { t as generateKotlinClient } from "./generator-BvNpSarY.mjs";
-//#region src/client-target.ts
+import { n as kotlinClientWalk, t as generateKotlinClient } from "./generator-D4GvH1-a.mjs";
+import { defineClient } from "kizunajs/generator";
+import { z } from "zod";
 /**
-* A Kotlin client target for `kizuna.config.ts`.
+* A Kotlin client for `kizuna.config.ts`.
 *
 * @example
-* kotlinClient({ output: './api/APIClient.kt', package: 'com.example.api' });
+* kotlinClient({
+*     output: './api/APIClient.kt',
+*     package: 'com.example.api',
+* });
 */
-const kotlinClient = (options) => ({
-	kind: "kotlin",
-	output: options.output,
-	generate: (contract) => generateKotlinClient(contract, {
-		namespaceName: options.namespace ?? "API",
+const kotlinClient = defineClient({
+	target: "kotlin",
+	options: z.object({
+		/**
+		* Name of the generated namespace object.
+		*
+		* @default 'API'
+		*/
+		namespace: z.string().default("API"),
+		/**
+		* Package declaration for the generated file, e.g. `com.example.api`.
+		*/
+		package: z.string().optional(),
+		/**
+		* Convert wire field names to camelCase properties, mapping the wire name
+		* back via `@SerialName`.
+		*
+		* @default false
+		*/
+		camelCaseProperties: z.boolean().optional(),
+		/**
+		* Give every enum an `unknown` case, so a value the client has not been
+		* generated for decodes instead of throwing.
+		*
+		* @default false
+		*/
+		unknownEnumCase: z.boolean().optional()
+	}),
+	generate: ({ options, api }) => kotlinClientWalk(api, {
+		namespaceName: options.namespace,
 		packageName: options.package,
 		camelCaseProperties: options.camelCaseProperties,
 		unknownEnumCase: options.unknownEnumCase

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kizunajs/kotlin",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.20",
   "description": "Kotlin client generation for Kizuna.js APIs",
   "keywords": [
     "kizunajs",
@@ -60,18 +60,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@kizunajs/cli": "2.0.0-beta.2"
+    "@kizunajs/cli": "2.0.0-beta.20"
   },
   "peerDependencies": {
-    "zod": "^4.0.0",
-    "kizunajs": "2.0.0-beta.2"
+    "kizunajs": "2.0.0-beta.20",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
+    "kizunajs": "2.0.0-beta.20",
     "@types/node": "^22.9.0",
     "tsdown": "^0.21.0",
     "typescript": "^6.0.3",
-    "zod": "^4.0.0",
-    "kizunajs": "2.0.0-beta.2"
+    "zod": "^4.0.0"
   },
   "scripts": {
     "build": "tsdown src/index.ts src/cli.ts --format esm,cjs --dts --clean --external kizunajs --external @kizunajs/cli --external zod",