@bazo/openapi-client-generator 3.0.13

package/package.json

@@ -0,0 +1,22 @@
+{
+	"name": "@bazo/openapi-client-generator",
+	"version": "3.0.13",
+	"bin": {
+		"openapi-client-generator": "bin.js"
+	},
+	"files": [
+		"bin.js",
+		"skills"
+	],
+	"dependencies": {
+		"@apidevtools/swagger-parser": "^12.1.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/bazo/openapi-client-generator.git"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org"
+	}
+}

package/skills/generate-client/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: generate-client
+description: >
+  Run the @bazo/openapi-client-generator CLI to produce a typed API client
+  from an OpenAPI JSON spec. Covers CLI flags (-n/--name, -m/--mode),
+  positional arguments (spec path, output directory), generation modes
+  (full, playwright, swift, kotlin), output file naming, and npm script
+  integration. Load when generating, regenerating, or configuring the
+  openapi-client-generator CLI.
+type: core
+library: openapi-client-generator
+library_version: "3.0.0"
+sources:
+  - "bazo/openapi-client-generator:src/bin.ts"
+  - "bazo/openapi-client-generator:src/pipeline.ts"
+---
+
+# Generate Client
+
+## Setup
+
+```bash
+npm install -D @bazo/openapi-client-generator
+```
+
+Run the generator:
+
+```bash
+npx openapi-client api.json out/ -n MyClient -m full
+```
+
+Arguments and flags:
+
+| Position/Flag | Required | Description |
+| --- | --- | --- |
+| `<spec.json>` | yes | Path to a local OpenAPI JSON file |
+| `<output-dir>` | yes | Directory for the generated file |
+| `-n, --name` | yes | Client class name (must be a valid TypeScript identifier) |
+| `-m, --mode` | no | `full` (default), `playwright`, `swift`, or `kotlin` |
+
+Save as an npm script:
+
+```json
+{
+  "scripts": {
+    "generate-api": "openapi-client api.json src/generated/ -n ApiClient -m full"
+  }
+}
+```
+
+## Core Patterns
+
+### Generate a full-mode TypeScript client (React Query + Wretch + Zod)
+
+```bash
+npx openapi-client openapi.json src/api/ -n ApiClient -m full
+```
+
+Produces `src/api/ApiClient.ts` with Zod schemas, React Query hooks, and a client class.
+
+### Generate a Playwright test client
+
+```bash
+npx openapi-client openapi.json tests/api/ -n TestApi -m playwright
+```
+
+Produces `tests/api/TestApi.ts` with async methods wrapping Playwright's `APIRequestContext`.
+
+### Generate a Swift client
+
+```bash
+npx openapi-client openapi.json Sources/API/ -n ApiClient -m swift
+```
+
+Produces `Sources/API/ApiClient.swift` with Codable structs and URLSession-based async methods.
+
+### Generate a Kotlin client
+
+```bash
+npx openapi-client openapi.json src/main/kotlin/api/ -n ApiClient -m kotlin
+```
+
+Produces `src/main/kotlin/api/ApiClient.kt` with `@Serializable` data classes and Ktor suspend functions.
+
+## Common Mistakes
+
+### CRITICAL Hallucinating non-existent CLI flags
+
+Wrong:
+
+```bash
+npx openapi-client api.json out/ -n MyClient --format json --validate --strict
+```
+
+Correct:
+
+```bash
+npx openapi-client api.json out/ -n MyClient -m full
+```
+
+The CLI uses `parseArgs` with `strict: true`. Only `-n/--name`, `-m/--mode`, `-v/--version`, and `-h/--help` exist. Any other flag causes a hard error.
+
+Source: src/bin.ts
+
+### HIGH Wrong positional argument order
+
+Wrong:
+
+```bash
+npx openapi-client out/ api.json -n MyClient
+```
+
+Correct:
+
+```bash
+npx openapi-client api.json out/ -n MyClient
+```
+
+The first positional must be the spec file path, the second must be the output directory. Swapping them causes the tool to try reading a directory as a JSON file.
+
+Source: src/bin.ts
+
+### HIGH Omitting the required --name flag
+
+Wrong:
+
+```bash
+npx openapi-client api.json out/ -m full
+```
+
+Correct:
+
+```bash
+npx openapi-client api.json out/ -n MyClient -m full
+```
+
+The `-n/--name` flag is required. It sets the exported class name and output filename. The CLI exits with an error if missing.
+
+Source: src/bin.ts
+
+### HIGH Passing a YAML spec or URL instead of a JSON file
+
+Wrong:
+
+```bash
+npx openapi-client https://api.example.com/openapi.yaml out/ -n MyClient
+```
+
+Correct:
+
+```bash
+npx openapi-client ./openapi.json out/ -n MyClient
+```
+
+The parser expects a local JSON file path. YAML specs and remote URLs are not supported.
+
+Source: src/parser/openapi-parser.ts
+
+### HIGH Using an invalid mode name
+
+Wrong:
+
+```bash
+npx openapi-client api.json out/ -n MyClient -m react-query
+```
+
+Correct:
+
+```bash
+npx openapi-client api.json out/ -n MyClient -m full
+```
+
+Mode must be exactly `full`, `playwright`, `swift`, or `kotlin`. Aliases like `react-query`, `ts`, `ios`, or `android` are not recognized.
+
+Source: src/bin.ts
+
+See also: integrate-full-client/SKILL.md — peer deps and client instantiation for full mode
+See also: integrate-playwright-client/SKILL.md — Playwright fixture setup for playwright mode
+See also: integrate-swift-client/SKILL.md — Xcode integration for swift mode
+See also: integrate-kotlin-client/SKILL.md — Ktor setup for kotlin mode

package/skills/integrate-full-client/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: integrate-full-client
+description: >
+  Use the generated full-mode TypeScript client in a web application.
+  Covers peer dependencies (zod, wretch, @tanstack/react-query), client
+  class instantiation with baseUrl and QueryClient, React Query useQuery
+  and useMutation hooks, Wretch HTTP configuration via onHttpConfigure,
+  ApiResponse<T> type, query invalidation, and GenericWretchError. Load
+  when importing or using a generated full-mode client file.
+type: framework
+library: openapi-client-generator
+library_version: "3.0.0"
+requires:
+  - generate-client
+sources:
+  - "bazo/openapi-client-generator:src/modes/full/index.ts"
+  - "bazo/openapi-client-generator:src/modes/full/query.ts"
+  - "bazo/openapi-client-generator:src/modes/full/mutation.ts"
+---
+
+This skill builds on generate-client. Read it first for CLI usage.
+
+# Integrate Full Client
+
+## Setup
+
+Install peer dependencies required by the generated file:
+
+```bash
+npm install zod wretch @tanstack/react-query
+```
+
+Instantiate the client:
+
+```typescript
+import { QueryClient } from "@tanstack/react-query";
+import { MyClient } from "./generated/MyClient";
+
+const queryClient = new QueryClient();
+const api = new MyClient("https://api.example.com", queryClient);
+```
+
+The constructor signature is:
+
+```typescript
+constructor(
+  baseUrl: string,
+  queryClient: QueryClient,
+  options?: RequestInit,
+  onHttpConfigure?: (w: Http) => Http
+)
+```
+
+## Core Patterns
+
+### Use a generated query hook in a React component
+
+```typescript
+function TaskList() {
+  const { data, isLoading } = api.listTasks.useQuery({ page: 1, limit: 10 });
+
+  if (isLoading) return <div>Loading...</div>;
+  return <div>{data?.data.items.map(t => <div key={t.id}>{t.title}</div>)}</div>;
+}
+```
+
+Each query operation exposes `.useQuery(params, options?)` which returns a standard React Query result extended with `.key` (the query key) and `.invalidate()` (shortcut for `queryClient.invalidateQueries`).
+
+### Use a generated mutation hook
+
+```typescript
+function CreateTask() {
+  const { mutate, isPending } = api.createTask.useMutation({
+    onSuccess: () => api.listTasks.useQuery.invalidate?.(),
+  });
+
+  return (
+    <button onClick={() => mutate({ body: { title: "New task", status: "todo" } })} disabled={isPending}>
+      Create
+    </button>
+  );
+}
+```
+
+Each mutation operation exposes `.useMutation(options?)`.
+
+### Use the query function directly (outside React)
+
+```typescript
+const result = await api.listTasks.query({ page: 1, limit: 10 });
+console.log(result.data); // typed response body
+console.log(result.status); // HTTP status code
+```
+
+Every operation also exposes a `.query()` or `.mutation()` function for non-React usage.
+
+### Configure HTTP with auth headers
+
+```typescript
+const api = new MyClient(
+  "https://api.example.com",
+  queryClient,
+  undefined,
+  (http) => http.auth(`Bearer ${token}`)
+);
+```
+
+The `onHttpConfigure` callback receives a Wretch instance and must return one. Use it to add auth, interceptors, or middleware.
+
+## Common Mistakes
+
+### CRITICAL Missing peer dependencies
+
+Wrong:
+
+```bash
+npm install zod
+# Generated file fails: Cannot find module 'wretch'
+```
+
+Correct:
+
+```bash
+npm install zod wretch @tanstack/react-query
+```
+
+The generated full-mode file imports from `zod`, `wretch`, `wretch/addons/queryString`, and `@tanstack/react-query`. All four must be installed in the consuming project.
+
+Source: src/modes/full/index.ts generateImports
+
+### CRITICAL Instantiating client without QueryClient
+
+Wrong:
+
+```typescript
+const api = new MyClient("https://api.example.com");
+```
+
+Correct:
+
+```typescript
+import { QueryClient } from "@tanstack/react-query";
+const queryClient = new QueryClient();
+const api = new MyClient("https://api.example.com", queryClient);
+```
+
+The constructor requires both `baseUrl` and a `QueryClient` instance. The client uses a Proxy to lazily bind operations to the HTTP instance and QueryClient — without the QueryClient, hooks will fail at runtime.
+
+Source: src/modes/full/index.ts generateClient
+
+### HIGH Editing the generated file directly
+
+Wrong:
+
+```typescript
+// Manually adding a custom method to MyClient.ts
+export class MyClient {
+  // ...generated code...
+  async customMethod() { /* hand-written */ }
+}
+```
+
+Correct:
+
+```typescript
+// Extend or wrap the generated client in a separate file
+import { MyClient } from "./generated/MyClient";
+
+class ExtendedClient extends MyClient {
+  async customMethod() { /* hand-written */ }
+}
+```
+
+The generated output is meant to be regenerated from the spec. Manual edits are overwritten on the next generation run.
+
+Source: maintainer interview
+
+See also: generate-client/SKILL.md — CLI usage for regenerating the client

package/skills/integrate-kotlin-client/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: integrate-kotlin-client
+description: >
+  Use the generated Kotlin client in an Android or JVM application. Covers
+  Ktor HttpClient and kotlinx.serialization dependencies, instantiation
+  with HttpClient and baseUrl string, suspend operation functions in
+  coroutine scope, @Serializable data classes, ApiResponse<T>, ApiException
+  handling, and content negotiation setup. Load when importing or using a
+  generated kotlin-mode client file.
+type: framework
+library: openapi-client-generator
+library_version: "3.0.0"
+requires:
+  - generate-client
+sources:
+  - "bazo/openapi-client-generator:src/modes/kotlin/index.ts"
+  - "bazo/openapi-client-generator:src/modes/kotlin/query.ts"
+  - "bazo/openapi-client-generator:src/modes/kotlin/mutation.ts"
+---
+
+This skill builds on generate-client. Read it first for CLI usage.
+
+# Integrate Kotlin Client
+
+## Setup
+
+Add dependencies to `build.gradle.kts`:
+
+```kotlin
+plugins {
+    kotlin("plugin.serialization") version "2.1.0"
+}
+
+dependencies {
+    implementation("io.ktor:ktor-client-core:3.1.0")
+    implementation("io.ktor:ktor-client-cio:3.1.0")
+    implementation("io.ktor:ktor-client-content-negotiation:3.1.0")
+    implementation("io.ktor:ktor-serialization-kotlinx-json:3.1.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.0")
+}
+```
+
+Instantiate the client:
+
+```kotlin
+import io.ktor.client.*
+import io.ktor.client.plugins.contentnegotiation.*
+import io.ktor.serialization.kotlinx.json.*
+
+val httpClient = HttpClient(CIO) {
+    install(ContentNegotiation) {
+        json()
+    }
+}
+
+val api = ApiClient(client = httpClient, baseUrl = "https://api.example.com")
+```
+
+The constructor signature is:
+
+```kotlin
+class ApiClient(
+    private val client: HttpClient,
+    private val baseUrl: String
+)
+```
+
+## Core Patterns
+
+### Call a query operation
+
+```kotlin
+runBlocking {
+    val result = api.listTasks(page = 1, limit = 10)
+    println(result.data.items) // List<Task>
+    println(result.status) // 200
+}
+```
+
+All operations are `suspend` functions. Query parameters map to function parameters with defaults for optional ones.
+
+### Call a mutation operation
+
+```kotlin
+runBlocking {
+    val result = api.createTask(
+        body = CreateTaskRequest(title = "Build feature", status = "todo")
+    )
+    println(result.data.id) // created task ID
+}
+```
+
+Mutations take a `body` parameter typed as the corresponding `@Serializable` data class.
+
+### Handle API errors
+
+```kotlin
+runBlocking {
+    try {
+        val result = api.getTask(taskId = "nonexistent")
+    } catch (e: ApiException) {
+        println("HTTP ${e.statusCode}: ${e.body}")
+        println("URL: ${e.responseUrl}")
+    }
+}
+```
+
+Non-success responses throw `ApiException` with `statusCode`, `body`, `responseHeaders`, and `responseUrl`.
+
+## Common Mistakes
+
+### CRITICAL Missing Ktor or kotlinx.serialization dependencies
+
+Wrong:
+
+```kotlin
+// build.gradle.kts — missing ktor and serialization deps
+dependencies {
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
+}
+```
+
+Correct:
+
+```kotlin
+dependencies {
+    implementation("io.ktor:ktor-client-core:3.1.0")
+    implementation("io.ktor:ktor-client-cio:3.1.0")
+    implementation("io.ktor:ktor-client-content-negotiation:3.1.0")
+    implementation("io.ktor:ktor-serialization-kotlinx-json:3.1.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.0")
+}
+```
+
+The generated file imports `io.ktor.client.*` and `kotlinx.serialization.*`. Both Ktor client (with a chosen engine like CIO) and kotlinx-serialization-json must be in the project dependencies.
+
+Source: src/modes/kotlin/index.ts generateImports
+
+### HIGH Calling suspend functions outside coroutine scope
+
+Wrong:
+
+```kotlin
+fun main() {
+    val result = api.getTask(taskId = "123") // Compilation error
+}
+```
+
+Correct:
+
+```kotlin
+suspend fun main() {
+    val result = api.getTask(taskId = "123")
+}
+```
+
+All generated operations are `suspend` functions. They must be called from a coroutine scope, a `suspend` function, or a builder like `runBlocking`.
+
+Source: src/modes/kotlin/query.ts
+
+### HIGH Editing the generated file directly
+
+Wrong:
+
+```kotlin
+// Adding a custom method directly in ApiClient.kt
+class ApiClient(private val client: HttpClient, private val baseUrl: String) {
+    // ...generated code...
+    suspend fun customMethod() { /* hand-written */ }
+}
+```
+
+Correct:
+
+```kotlin
+// Extend via extension functions in a separate file
+suspend fun ApiClient.customMethod() {
+    /* hand-written */
+}
+```
+
+The generated output is meant to be regenerated from the spec. Manual edits are overwritten on the next generation run. Use Kotlin extension functions in a separate file for custom methods.
+
+Source: maintainer interview
+
+See also: generate-client/SKILL.md — CLI usage for regenerating the client