@ir-kit/kit 0.0.0-stage → 1.0.0

package/docs/sdk-go.md

@@ -0,0 +1,277 @@
+# @ir-kit/kit/sdk/go
+
+Generate idiomatic Go client SDKs from an OpenAPI 3.x spec — `encoding/json` structs, typed-string enums, per-tag interfaces with `context.Context` first-arg + `*WithResponse` companions, and a `net/http`-backed impl struct. Per-call `RequestOptions`, composable interceptors, typed `APIError`, multipart + form-urlencoded wire encoding, multi-2xx sealed-style returns, and per-op security auto-wiring all included. Zero runtime dependencies — stdlib only.
+
+Specs are loaded with `@hey-api/json-schema-ref-parser` and read through ir-kit's own model (`@ir-kit/kit/ir`). 2.0 / 3.0 / 3.1 inputs all produce the same output. Through `ir sdk go` or `ir generate`, an AsyncAPI file gives one model type per message.
+
+Sibling package to [`@ir-kit/kit/sdk/kotlin`](../openapi-kotlin) and [`@ir-kit/kit/sdk/swift`](../openapi-swift). Part of [ir-kit](https://github.com/ahmedrowaihi/ir-kit). Companion to the [`petstore` example](../../../examples/petstore).
+
+## Install
+
+```bash
+pnpm add @ir-kit/kit @hey-api/shared @hey-api/spec-types
+```
+
+## Usage
+
+```ts
+import { generate } from "@ir-kit/kit/sdk/go";
+
+await generate({
+  input: "https://api.example.com/openapi.json",
+  output: "./sdk-go",
+  packageName: "petstore",
+});
+```
+
+Reads any of: a filesystem path, an http(s) URL, or a pre-parsed object. YAML and JSON are both supported. External `$ref`s are bundled inline.
+
+## Output
+
+### Schemas → structs / typed-string enums / type aliases
+
+```go
+type Pet struct {
+    Id        *int64    `json:"id,omitempty"`
+    Name      string    `json:"name"`
+    Category  *Category `json:"category,omitempty"`
+    PhotoUrls []string  `json:"photoUrls"`
+    Tags      []Tag     `json:"tags,omitempty"`
+    Status    *PetStatus `json:"status,omitempty"`
+}
+
+type PetStatus string
+
+const (
+    PetStatusAvailable PetStatus = "available"
+    PetStatusPending   PetStatus = "pending"
+    PetStatusSold      PetStatus = "sold"
+)
+```
+
+Optional fields use pointer types (`*int64`, `*Category`) + `omitempty` so JSON can distinguish absent from zero. Required fields are bare. Slices and maps are nilable in Go and get `omitempty` without pointer-wrapping.
+
+### Operations → interfaces + impls
+
+For each tag the generator emits:
+
+- `type <Tag>API interface` with one method per op + a `*WithResponse` twin that returns the raw `*http.Response`
+- `type NetHTTP<Tag>API struct { client *APIClient }` impl
+- `func NewNetHTTP<Tag>API(client *APIClient) *NetHTTP<Tag>API` constructor
+
+```go
+type PetAPI interface {
+    // GET /pet/{petId}
+    GetPetById(ctx context.Context, petId int64, opts RequestOptions) (*Pet, error)
+    GetPetByIdWithResponse(ctx context.Context, petId int64, opts RequestOptions) (*Pet, *http.Response, error)
+    // …
+}
+
+type NetHTTPPetAPI struct {
+    client *APIClient
+}
+
+func NewNetHTTPPetAPI(client *APIClient) *NetHTTPPetAPI {
+    return &NetHTTPPetAPI{client: client}
+}
+```
+
+Method conventions:
+- **`ctx context.Context`** is the first arg — Go's idiomatic cancellation/deadline channel; replaces the `timeout` field that swift/kotlin's `RequestOptions` carries (`opts.Timeout` is still available as a convenience knob).
+- **`opts RequestOptions`** is the trailing arg — same shape as kotlin/swift.
+- **Named returns** (`(result *Pet, err error)`) so err-check sites do bare `return` without zero-value matching.
+- **No method overloading** — `*WithResponse` is a separately named method (Go has no overloads).
+
+### Per-call control via `RequestOptions`
+
+```go
+type RequestOptions struct {
+    Client               *APIClient
+    BaseURL              string
+    Timeout              time.Duration
+    Headers              map[string]string
+    RequestInterceptors  []func(*http.Request) (*http.Request, error)
+    ResponseValidator    func(body []byte, resp *http.Response) error
+    ResponseTransformer  func(body []byte) ([]byte, error)
+}
+```
+
+```go
+pets.GetPetById(ctx, 1, RequestOptions{})                                    // defaults
+pets.GetPetById(ctx, 1, RequestOptions{Client: customClient})                // swap transport
+pets.GetPetById(ctx, 1, RequestOptions{Headers: map[string]string{"X-Trace": id}})
+pets.GetPetById(ctx, 1, RequestOptions{BaseURL: "https://staging.example.com/api/v3"})
+pets.GetPetById(ctx, 1, RequestOptions{Timeout: 60 * time.Second})
+```
+
+### Composable interceptors + auth
+
+The runtime `APIClient` carries an `Interceptors` slice that runs against every outgoing request. Interceptors compose — auth, logging, tracing all coexist:
+
+```go
+client := NewAPIClient("https://api.example.com/")
+client.Interceptors = append(client.Interceptors, func(req *http.Request) (*http.Request, error) {
+    req.Header.Set("Authorization", "Bearer "+TokenStore.Access())
+    return req, nil
+})
+```
+
+When the spec declares any `securitySchemes`, the generator additionally emits an `Auth` interface (with `BearerAuth`, `APIKeyAuth`, `BasicAuth` concrete types — `APIKeyAuth` carries an `APIKeyLocation` of `Header` / `Query` / `Cookie`) and the client gains an `Auth map[string]Auth` keyed by scheme name. Operations with `security:` requirements walk the map and apply the matching scheme automatically:
+
+```go
+client.Auth["petstore_auth"] = BearerAuth{Token: token}
+client.Auth["api_key"] = APIKeyAuth{Name: "X-API-Key", Value: key, Location: APIKeyHeader}
+```
+
+### Body media-type dispatch
+
+| Input media type | Generated parameter | Wire encoding |
+|---|---|---|
+| `application/json` (and `+json`) | `body *T` | `json.Marshal(body)` |
+| `multipart/form-data` (object schema) | one param per property; binary fields → `[]byte` | emitted `MultipartFormBody` helper (wraps `mime/multipart`) |
+| `application/x-www-form-urlencoded` (object schema) | one param per property | `url.Values{}.Encode()` |
+| `application/octet-stream`, image, etc. | `body []byte` | raw bytes |
+| `oneOf` / unresolvable JSON | `body []byte` | raw bytes (caller pre-encodes) |
+
+### Typed errors
+
+Every non-2xx response funnels into `*APIError`:
+
+```go
+type APIError struct {
+    Kind       APIErrorKind
+    StatusCode int    // populated for ClientError / ServerError / Unexpected
+    Body       []byte // raw response body for HTTP errors
+    Cause      error  // underlying error for transport / encoding / decoding
+}
+```
+
+`APIErrorKind` is an `iota`-typed enum: `APIErrorKindClient` (4xx), `APIErrorKindServer` (5xx), `APIErrorKindUnexpected`, `APIErrorKindEncoding`, `APIErrorKindDecoding`, `APIErrorKindTransport`. Pattern-match with `errors.As`:
+
+```go
+var apiErr *APIError
+if errors.As(err, &apiErr) {
+    switch apiErr.Kind {
+    case APIErrorKindClient:  // 4xx — apiErr.StatusCode + apiErr.Body
+    case APIErrorKindServer:  // 5xx
+    case APIErrorKindTransport: // network / I/O — apiErr.Cause
+    }
+}
+```
+
+### Multi-2xx → sealed-style sum type
+
+When an operation declares more than one 2xx response code with distinct schemas, the generator emits a marker interface + concrete types — Go's idiomatic sum-type pattern:
+
+```go
+type SubmitJobResponse interface {
+    isSubmitJobResponse()
+}
+
+type SubmitJobResponseStatus200 struct{ Value JobResult }
+func (SubmitJobResponseStatus200) isSubmitJobResponse() {}
+
+type SubmitJobResponseStatus204 struct{}
+func (SubmitJobResponseStatus204) isSubmitJobResponse() {}
+```
+
+Callers dispatch with a type switch:
+
+```go
+result, err := jobs.SubmitJob(ctx, body, RequestOptions{})
+switch r := result.(type) {
+case SubmitJobResponseStatus200:
+    handle(r.Value)
+case SubmitJobResponseStatus204:
+    // empty 204
+}
+```
+
+## Generator options
+
+Every option is optional. Pass them to `generate({ ... })`:
+
+| Option | Purpose |
+|---|---|
+| `input` / `output` | Spec source (path / URL / object) and SDK output dir. |
+| `packageName` | Go package every file declares. Default `"api"`. |
+| `clean` | Wipe `output` before writing. Default `true`. Refuses to wipe cwd or filesystem root. |
+| `gomod` | Pass `{ module: "github.com/example/foo" }` to emit a minimal `go.mod` at the output root for standalone-module mode. Omit for drop-in mode. |
+| `defaultTag` | Tag to use when an op has none. Default `"Default"`. |
+| `interfaceName` | `(tag) => string`. Default `(tag) => `${PascalCase(tag)}API``. |
+| `clientStructName` | `(interfaceName) => string`. Default `(p) => `NetHTTP${p}``. |
+| `interfaceOnly` | Skip impl struct emission. Default `false`. |
+| `fileLocation` | `(decl) => { dir, file }` — full per-decl override. Rejects `..` traversal and absolute paths. |
+
+```ts
+generate({
+    input,
+    output,
+    packageName: "petstore",
+    gomod: { module: "github.com/example/petstore-sdk" },
+});
+```
+
+## Two consumption modes
+
+| Mode | Setup | When |
+|---|---|---|
+| **Drop into an existing module** | Paste the `.go` files into your module's source tree under any directory; they all declare the same `package <packageName>`. No third-party deps needed. | Adding the SDK directly to one app or service. |
+| **Standalone Go module** | Pass `gomod: { module: "..." }` to `generate()`; a minimal `go.mod` is emitted at the output root. Run `go build ./...` from the output dir. | Sharing across multiple modules or publishing as a separate Git repo. |
+
+## Output layout
+
+```text
+sdk-go/
+├── pet.go                          # struct
+├── pet_status.go                   # type alias + const block (enum)
+├── pet_api.go                      # interface
+├── net_http_pet_api.go             # impl struct + constructor + all methods
+├── api_client.go                   # runtime helper (transport, dispatch, decode)
+├── api_error.go                    # typed errors
+├── auth.go                         # (when spec has securitySchemes)
+├── api_key_location.go             # (when spec has securitySchemes)
+├── multipart_form_body.go          # (when any op uses multipart/form-data)
+├── url_encoding.go                 # query helpers
+├── query_style.go                  # form / spaceDelimited / pipeDelimited
+├── request_options.go
+└── (go.mod when `gomod:` is set)
+```
+
+Conventions:
+- One file per type (struct / interface / typed-string enum) — Go convention.
+- All methods on a receiver collapse into one file (`net_http_<tag>_api.go`).
+- Snake_case file names that respect acronyms (`NetHTTPPetAPI` → `net_http_pet_api.go`).
+- Sealed-style multi-2xx response types (interface + concrete cases + marker methods) collapse into a single file named after the interface.
+
+## Requirements
+
+- **Go** 1.22 or newer (uses generics for `Execute[T]`).
+- **No third-party dependencies** — the SDK uses only stdlib (`net/http`, `encoding/json`, `mime/multipart`, `context`, …).
+
+## API surface
+
+| Export | Purpose |
+|---|---|
+| `generate(opts)` | High-level entry: load → IR → decls → files on disk. |
+| `schemasToDecls(schemas)` | `IR.Model.components.schemas` → `GoDecl[]`. |
+| `operationsToDecls(paths, opts?)` | `IR.PathsObject` → `{ decls, needsAuth, needsMultipart }`. |
+| `buildGoProject(decls, opts?)` | `GoDecl[]` → `{ path, content }[]` with package / import resolution. |
+| `buildRuntimeFiles(opts, pkg)` | Standalone runtime helper files (APIClient, APIError, …). |
+| `gomodFile(opts)` | Build a minimal `go.mod` for standalone-module mode. |
+| `securityKey(path, method)` | Key into `OperationsOptions.securitySchemeNames`. |
+| `printFile(file)` / `go*` builders | Lower-level Go AST + printer. |
+
+```text
+src/ast/                      go* builders returning ir-kit nodes; GoDecl
+src/go-compiler/              printFile / printDecl via ir-kit
+src/ir/
+├── type/                     Schema → GoType
+├── operation/                IR.OperationObject → signature shared by interface + impl
+├── impl/                     net/http body builders (url, request, headers, body, decode)
+├── runtime/                  Copies runtime/*.go into the SDK
+├── schema.ts                 schemasToDecls
+└── operations.ts             paths → interfaces + impl structs (orchestrator)
+```
+
+Per-method bodies are built as `@ir-kit/kit/codegen` nodes; imports are collected from those nodes. Runtime helpers (the same Go every time) are real, vetted sources in `runtime/` and are copied with the package clause rewritten.

package/docs/sdk-java.md

@@ -0,0 +1,28 @@
+# @ir-kit/kit/sdk/java
+
+Generate a Java 17 client SDK from an OpenAPI 3.x spec.
+
+- Models are `record`s; string enums carry their wire value via `@JsonValue`.
+- One `<Tag>Api` interface per tag plus an `Http<Tag>Api` implementation.
+- HTTP uses the JDK's `java.net.http.HttpClient`; JSON uses Jackson.
+- The runtime (`ApiClient`, `RequestOptions`, `Auth`, …) ships as plain Java sources under `runtime/`.
+
+```ts
+import { generate } from "@ir-kit/kit/sdk/java";
+
+await generate({
+  input: "petstore.yaml",
+  output: "sdk",
+  packageName: "com.example.petstore",
+  gradle: true,
+});
+```
+
+```java
+var client = new ApiClient(URI.create("https://petstore.example.com/v3"));
+client.auth.put("api_key", new Auth.ApiKey("api_key", "secret", ApiKeyLocation.HEADER));
+PetApi pets = new HttpPetApi(client);
+Pet pet = pets.getPetById(1L);
+```
+
+Runtime dependencies: `com.fasterxml.jackson.core:jackson-databind` and `com.fasterxml.jackson.datatype:jackson-datatype-jsr310`.

package/docs/sdk-k6.md

@@ -0,0 +1,46 @@
+# @ir-kit/kit/sdk/k6
+
+Standalone programmatic generator: OpenAPI 3.x spec → typed [k6](https://k6.io) client + TS types + faker-backed data builders. Same shape as `@ir-kit/kit/sdk/swift`, `@ir-kit/kit/sdk/go`, `@ir-kit/kit/sdk/kotlin` — pure `generate({ spec, output })`, no hey-api plugin runner required at the call site.
+
+## Use cases
+
+- The [@ir-kit/k6-tools](../tools) CLI uses this internally for `k6-tools sync` and `k6-tools init`.
+- Embedding in your own tooling (MCP servers, internal CLIs, custom generators).
+- The [@ir-kit/kit/openapi-ts/k6](../hey-api) hey-api plugin wraps this when you prefer the `openapi-ts.config.ts` workflow.
+
+## Usage
+
+```ts
+import { generate } from "@ir-kit/kit/sdk/k6";
+
+await generate({
+  input: "./openapi.yaml",         // path | URL | parsed spec object
+  output: "./src/gen",
+  defaultBaseUrl: "https://api.example.com",   // optional override
+  normalize: true,                              // safe normalize preset
+});
+```
+
+Emits four files under `output`:
+
+| File         | Contents                                                                       |
+| ------------ | ------------------------------------------------------------------------------ |
+| `types.ts`   | One `export type <Name>` per spec schema. Object schemas → type literals; enums → string-literal unions; refs → `TypeReferenceNode`s. |
+| `client.ts`  | One `export function <opId>(...)` per spec operation. Path/query/body/headers typed; returns the parsed JSON response (`__parseJson<T>`). Each call tags `{ operation: <opId> }` and reads middleware headers from `@ir-kit/k6/runtime`. |
+| `data.ts`    | `data.<TypeName>(overrides?)` builders — `@faker-js/faker` underneath. Format-aware (uuid, email, date-time, …) and refs resolve to nested `data.<X>()` calls so cycles stay lazy. |
+| `index.ts`   | Re-exports the above (`* from client`, `* as types from types`, `data`). |
+
+## Shape
+
+Internally:
+1. `@hey-api/json-schema-ref-parser` bundles external refs.
+2. `@ir-kit/kit/openapi`'s `normalizeSpec` runs (optional, on by default).
+3. `parseOpenAPI` from `@ir-kit/kit/ir` reads it into ir-kit's model.
+4. Operation + schema walkers emit `ts.factory` AST → printed with `ts.createPrinter`.
+
+That's it — no hey-api plugin runner is loaded, no `$` DSL is touched.
+
+## See also
+
+- [@ir-kit/k6](../framework) — runtime framework consumed by the generated client
+- [@ir-kit/k6-tools](../tools) — CLI built on top of this

package/docs/sdk-kotlin.md

@@ -0,0 +1,259 @@
+# @ir-kit/kit/sdk/kotlin
+
+Generate idiomatic Android / JVM Kotlin client SDKs from an OpenAPI 3.x spec — `@Serializable` data classes, `String`-raw enums, per-tag interfaces with `suspend` functions, and an OkHttp + kotlinx-serialization impl class. Per-call `RequestOptions`, composable interceptors, typed `APIError`, multipart + form-urlencoded wire encoding, multi-2xx sum-type returns, and per-op security auto-wiring all included.
+
+Built on the [`@hey-api`](https://github.com/hey-api/openapi-ts) toolchain (`@hey-api/json-schema-ref-parser` for spec loading, `@hey-api/shared` IR for normalization). 2.0 / 3.0 / 3.1 inputs all produce the same output.
+
+Sibling package to [`@ir-kit/kit/sdk/swift`](../openapi-swift). Part of [ir-kit](https://github.com/ahmedrowaihi/ir-kit). Companion to the [`petstore` example](../../../examples/petstore).
+
+## Install
+
+```bash
+pnpm add @ir-kit/kit @hey-api/shared @hey-api/spec-types
+```
+
+## Usage
+
+```ts
+import { generate } from "@ir-kit/kit/sdk/kotlin";
+
+await generate({
+  input: "https://api.example.com/openapi.json",
+  output: "./sdk-kotlin",
+  packageName: "com.example.petstore",
+});
+```
+
+Reads any of: a filesystem path, an http(s) URL, or a pre-parsed object. YAML and JSON are both supported. External `$ref`s are bundled inline.
+
+## Output
+
+### Schemas → `@Serializable` data classes / enums / typealiases
+
+```kotlin
+@Serializable
+public data class Pet(
+    public val id: Long? = null,
+    public val name: String,
+    public val category: Category? = null,
+    public val photoUrls: List<String>,
+    public val tags: List<Tag>? = null,
+    public val status: PetStatus? = null,
+)
+
+@Serializable
+public enum class PetStatus(public val raw: String) {
+    @SerialName("available") AVAILABLE("available"),
+    @SerialName("pending") PENDING("pending"),
+    @SerialName("sold") SOLD("sold"),
+}
+```
+
+Inline enums on a property get promoted to a top-level `OwnerProperty` enum class. Renamed JSON keys (snake_case → camelCase) get a `@SerialName` so the wire format stays untouched.
+
+### Operations → interfaces + impls
+
+For each tag the generator emits:
+
+- `interface <Tag>Api` with `suspend fun` requirements
+- top-level `<Tag>Api.<op>(…)` extension funs as no-options convenience overloads (forward to the with-options form using `RequestOptions()` defaults)
+- `class OkHttp<Tag>Api(client: APIClient) : <Tag>Api` with the wire impl
+
+```kotlin
+public interface PetApi {
+    /** GET /pet/{petId} */
+    public suspend fun getPetById(petId: Long, options: RequestOptions): Pet
+    public suspend fun getPetByIdWithResponse(petId: Long, options: RequestOptions): Pair<Pet, Response>
+    // …
+}
+
+public suspend fun PetApi.getPetById(petId: Long): Pet =
+    getPetById(petId = petId, options = RequestOptions())
+
+public class OkHttpPetApi(public val client: APIClient) : PetApi {
+    public override suspend fun getPetById(petId: Long, options: RequestOptions): Pet { /* … */ }
+    // …
+}
+```
+
+Every operation also emits a sibling `*WithResponse` overload that returns `Pair<T, Response>` — for callers that need response headers (pagination cursors, `ETag`, rate limits). Void-returning operations get `*WithResponse(): Response` instead.
+
+### Per-call control via `RequestOptions`
+
+```kotlin
+public data class RequestOptions(
+    public val client: APIClient? = null,
+    public val baseUrl: HttpUrl? = null,
+    public val timeout: Long? = null,                                    // milliseconds
+    public val headers: Map<String, String> = emptyMap(),
+    public val requestInterceptors: List<suspend (Request) -> Request> = emptyList(),
+    public val responseValidator: (suspend (ByteArray, Response) -> Unit)? = null,
+    public val responseTransformer: (suspend (ByteArray) -> ByteArray)? = null,
+)
+```
+
+```kotlin
+pets.getPetById(1)                                                       // defaults
+pets.getPetById(1, RequestOptions(client = customClient))                // swap transport
+pets.getPetById(1, RequestOptions(headers = mapOf("X-Trace" to id)))     // extra headers
+pets.getPetById(1, RequestOptions(baseUrl = stagingUrl))                 // hit staging
+pets.getPetById(1, RequestOptions(timeout = 60_000))                     // long-poll override
+```
+
+### Composable interceptors + auth
+
+The runtime `APIClient` carries an `interceptors.request` list that runs against every outgoing request. Interceptors compose — auth, logging, tracing all coexist:
+
+```kotlin
+val client = APIClient(baseUrl = "https://api.example.com/".toHttpUrl())
+client.interceptors.request += { request ->
+    request.newBuilder()
+        .header("Authorization", "Bearer ${TokenStore.access()}")
+        .build()
+}
+```
+
+When the spec declares any `securitySchemes`, the generator additionally emits an `Auth` sealed class (with `Bearer`, `ApiKey`, `Basic` subclasses — `ApiKey` carries an `APIKeyLocation` of `HEADER` / `QUERY` / `COOKIE`) and the client gains a `var auth: MutableMap<String, Auth>` keyed by scheme name. Operations with `security:` requirements walk the map and apply the matching scheme automatically:
+
+```kotlin
+client.auth["bearerAuth"] = Auth.Bearer(token)
+client.auth["xApiKey"] = Auth.ApiKey("X-API-Key", key, APIKeyLocation.HEADER)
+```
+
+### Body media-type dispatch
+
+| Input media type | Generated parameter shape | Wire encoding |
+|---|---|---|
+| `application/json` (and `+json`) | `body: T` | `Json.encodeToString(<ser>, body).toRequestBody("application/json".toMediaType())` |
+| `multipart/form-data` (object schema) | one param per property; binary fields → `ByteArray` | emitted `MultipartFormBody` helper (wraps `MultipartBody.Builder`) |
+| `application/x-www-form-urlencoded` (object schema) | one param per property | `FormBody.Builder()` |
+| `application/octet-stream`, image, etc. | `body: ByteArray` | raw bytes via `toRequestBody("<mt>".toMediaType())` |
+| `oneOf` / unresolvable JSON | `body: ByteArray` | raw bytes (caller pre-encodes) |
+
+### Typed errors
+
+Every non-2xx response funnels into `APIError`:
+
+```kotlin
+public sealed class APIError(message: String? = null, cause: Throwable? = null) :
+    RuntimeException(message, cause) {
+    public class ClientError(public val statusCode: Int, public val body: ByteArray) : APIError(/* … */)   // 4XX
+    public class ServerError(public val statusCode: Int, public val body: ByteArray) : APIError(/* … */)   // 5XX
+    public class UnexpectedStatus(public val statusCode: Int, public val body: ByteArray) : APIError(/* … */) // 1XX/3XX/etc.
+    public class DecodingFailed(cause: Throwable) : APIError(/* … */)                                       // kotlinx-serialization threw
+    public class Transport(cause: Throwable) : APIError(/* … */)                                            // OkHttp/network layer
+}
+```
+
+### Multi-2xx → sum-type return
+
+When an operation declares more than one 2xx response code with distinct schemas, the generator emits a sealed-class hierarchy and the impl dispatches on `response.code`:
+
+```kotlin
+public sealed class SubmitJobResponse {
+    public data class Status200(public val value: JobResult) : SubmitJobResponse()
+    public data class Status202(public val value: Pending) : SubmitJobResponse()
+    public object Status204 : SubmitJobResponse()
+}
+```
+
+## Generator options
+
+Every option is optional. Pass them to `generate({ ... })`:
+
+| Option | Purpose |
+|---|---|
+| `input` / `output` | Spec source (path / URL / object) and SDK output dir. |
+| `packageName` | Kotlin package every file declares. Default `"com.example.api"`. |
+| `clean` | Wipe `output` before writing. Default `true`. Refuses to wipe cwd or filesystem root. |
+| `gradle` | Emit `build.gradle.kts` + `settings.gradle.kts` for standalone-module mode. `true` → defaults. Object → custom `group`, `version`, plugin/dependency versions, JVM target. Omit → mode 1 (raw kotlin source tree only). |
+| `defaultTag` | Tag to use when an op has none. Default `"Default"`. |
+| `interfaceName` | `(tag) => string`. Default `(tag) => `${PascalCase(tag)}Api``. |
+| `clientClassName` | `(interfaceName) => string`. Default `(p) => `OkHttp${p}``. |
+| `interfaceOnly` | Skip impl class emission. Default `false`. |
+| `openImpl` | Emit impl class as `open` so consumers can subclass. Default `false`. |
+| `layout` | `"split"` (default — `api/` + `models/` sub-packages) or `"flat"` (one package). |
+| `fileLocation` | `(decl) => { dir }` — full per-decl override. Rejects `..` traversal and absolute paths. |
+
+```ts
+generate({
+    input,
+    output,
+    packageName: "com.example.petstore",
+    gradle: { group: "com.example", version: "1.0.0" },
+    openImpl: true,
+});
+```
+
+## Two consumption modes
+
+| Mode | Setup | When |
+|---|---|---|
+| **Drop into an existing Gradle module** | Paste the package directory (e.g. `com/example/petstore/`) into your module's `src/main/kotlin/` tree. The surrounding module must apply `kotlin("plugin.serialization")` and depend on OkHttp + kotlinx-serialization-json + kotlinx-coroutines-core + kotlinx-datetime. | Adding the SDK directly to one app or library. |
+| **Standalone Gradle module** | Pass `gradle: true` (or an options object) to `generate()`; `build.gradle.kts` + `settings.gradle.kts` are emitted at the output root and the source moves under `src/main/kotlin/`. Run `gradle build` from the output dir. | Sharing across multiple modules, publishing privately, or wanting a clean dependency boundary. |
+
+## Output layout
+
+```text
+sdk-kotlin/
+├── com/example/petstore/
+│   ├── api/
+│   │   ├── PetApi.kt                  # interface
+│   │   ├── PetApiExtensions.kt        # convenience overloads (no-options)
+│   │   ├── OkHttpPetApi.kt            # impl class
+│   │   ├── APIClient.kt               # runtime helper (transport, dispatch, decode)
+│   │   ├── APIInterceptors.kt         # interceptor pipeline
+│   │   ├── APIError.kt                # typed errors
+│   │   ├── Auth.kt                    # (when spec has securitySchemes)
+│   │   ├── APIKeyLocation.kt          # (when spec has securitySchemes)
+│   │   ├── MultipartFormBody.kt       # (when any op uses multipart/form-data)
+│   │   ├── URLEncoding.kt             # query helpers
+│   │   ├── QueryStyle.kt              # form / spaceDelimited / pipeDelimited
+│   │   └── RequestOptions.kt
+│   └── models/
+│       ├── Pet.kt                     # @Serializable data classes
+│       ├── PetStatus.kt              # enum classes
+│       └── …
+└── (build.gradle.kts + settings.gradle.kts when `gradle:` is set; the package tree then sits under src/main/kotlin/)
+```
+
+## Requirements
+
+The generated code uses Kotlin coroutines + kotlinx-serialization, so:
+
+- **Kotlin** 2.0 or newer (with `kotlin("plugin.serialization")` applied)
+- **JVM target** 17 or newer (configurable via the `gradle` option)
+
+Runtime dependencies (set up by the `gradle:` option, or by the consuming module in drop-in mode):
+
+- `org.jetbrains.kotlinx:kotlinx-serialization-json:1.7+`
+- `org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9+`
+- `org.jetbrains.kotlinx:kotlinx-datetime:0.6+` (only if any model uses `Instant` / `LocalDate`)
+- `com.squareup.okhttp3:okhttp:4.12+`
+
+## API surface
+
+| Export | Purpose |
+|---|---|
+| `generate(opts)` | High-level entry: load → IR → decls → files on disk. |
+| `schemasToDecls(schemas)` | `IR.Model.components.schemas` → `KtDecl[]`. |
+| `operationsToDecls(paths, opts?)` | `IR.PathsObject` → `{ decls, needsAuth, needsMultipart }` (interfaces + impls grouped by tag). |
+| `buildKotlinProject(decls, opts?)` | `KtDecl[]` → `{ path, content }[]` with package / import resolution. |
+| `buildRuntimeFiles(opts, pkg)` | Standalone runtime helper files (APIClient, APIError, …) keyed off the consumer's package. |
+| `buildGradleFile(opts?)` | Build a `build.gradle.kts` for a standalone Gradle module wrapping the SDK. |
+| `securityKey(path, method)` | Key into `OperationsOptions.securitySchemeNames`. |
+| `printFile(file)` / `kt*` builders | Lower-level Kotlin AST + printer. |
+
+```text
+src/ast/                      kt* builders returning ir-kit nodes; KtDecl
+src/kt-compiler/              printFile / printDecl via ir-kit
+src/ir/
+├── type/                     Schema → KtType
+├── operation/                IR.OperationObject → signature shared by interface + impl
+├── impl/                     OkHttp body builders (url, request, headers, body, decode)
+├── runtime/                  Copies runtime/*.kt into the SDK
+├── schema.ts                 schemasToDecls
+└── operations.ts             paths → interfaces + impl classes (orchestrator)
+```
+
+Per-method bodies are built as `@ir-kit/kit/codegen` nodes; imports are collected from those nodes. Runtime helpers (the same Kotlin every time) are real, ktlint-checked sources in `runtime/` and are copied with the package header rewritten.