@apollo-deploy/tesseract 1.9.0 → 2.1.0

package/templates/kotlin/client.hbs

@@ -3,11 +3,8 @@ package {{packageName}}
 import {{packageName}}.api.*
 import {{packageName}}.internal.Transport
 import {{packageName}}.internal.TransportConfig
-import kotlinx.coroutines.*
 
-/**
- * Configuration for the {{title}} API client.
- */
+/** Configuration for the {{title}} API client. */
 data class ClientConfig(
     val baseUrl: String = "{{baseUrl}}",
 {{#each securitySchemes}}
@@ -28,33 +25,39 @@ data class ClientConfig(
     val {{configKey}}: String? = null,
 {{/if}}
 {{/each}}
+    /** Headers sent with every request. */
+    val defaultHeaders: Map<String, String> = emptyMap(),
     /** Request timeout in milliseconds. */
-    val timeoutMs: Long = 15000,
-    /** Maximum number of retry attempts. */
+    val timeoutMs: Long = 15_000,
+    /** Number of retries after the initial request. */
     val maxRetries: Int = 3,
+    /** Allow automatic retries for POST and PATCH requests. */
+    val retryUnsafeRequests: Boolean = false,
 )
 
-/**
- * Primary API client for {{title}}.
- *
- * Provides access to all domain-specific API groups.
- */
+/** Primary API client for {{title}}. */
 class {{clientName}}Client(
-    config: ClientConfig = ClientConfig()
-) {
-    private val transport: Transport = Transport(
+    config: ClientConfig = ClientConfig(),
+) : AutoCloseable {
+    private val transport = Transport(
         TransportConfig(
             baseUrl = config.baseUrl,
 {{#each securitySchemes}}
             {{configKey}} = config.{{configKey}},
 {{/each}}
+            defaultHeaders = config.defaultHeaders,
             timeoutMs = config.timeoutMs,
             maxRetries = config.maxRetries,
-        )
+            retryUnsafeRequests = config.retryUnsafeRequests,
+        ),
     )
 
 {{#each groups}}
     /** {{#if description}}{{description}}{{else}}{{interfaceName}} operations.{{/if}} */
     val {{name}}: {{interfaceName}} = {{interfaceName}}(transport)
 {{/each}}
+
+    override fun close() {
+        transport.close()
+    }
 }

package/templates/kotlin/domain.hbs

@@ -2,70 +2,73 @@ package {{packageName}}.api
 
 import {{packageName}}.internal.Transport
 import {{packageName}}.models.*
-import io.ktor.http.*
-import kotlinx.coroutines.*
+import io.ktor.http.HttpMethod
+import io.ktor.http.encodeURLPathPart
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.encodeToJsonElement
 
-/**
- * {{#if description}}{{description}}{{else}}{{interfaceName}} API operations.{{/if}}
- */
+/** {{#if description}}{{description}}{{else}}{{interfaceName}} API operations.{{/if}} */
 class {{interfaceName}}(
-    private val transport: Transport
+    private val transport: Transport,
 ) {
 {{#each operations}}
-    {{#if summary}}
-    /**
-     * {{summary}}{{#if description}}
-     *
-     * {{description}}{{/if}}
-     */
-    {{/if}}
-    {{#if deprecated}}
-    @Deprecated(
-        message = "{{#if deprecationMessage}}{{deprecationMessage}}{{else}}This operation is deprecated.{{/if}}",
-    )
-    {{/if}}
-    suspend fun {{name}}(
+{{#if deprecated}}
+    @Deprecated("{{#if deprecationMessage}}{{deprecationMessage}}{{else}}This operation is deprecated.{{/if}}")
+{{/if}}
+    suspend fun {{methodName}}(
+{{#if hasParameters}}
+        {{{signature}}},
+{{/if}}
+    ): {{{targetResponseType}}} {
+        var path = "{{targetPath}}"
 {{#each pathParams}}
-        {{name}}: {{{kotlinType type}}},
+        path = path.replace("{{placeholder}}", {{parameterName}}.toString().encodeURLPathPart())
 {{/each}}
-{{#if requestBody}}
-        body: {{{requestBody.kotlinType}}},
+
+        val query = mutableMapOf<String, String?>()
+{{#each queryParams}}
+{{#if required}}
+        query["{{originalName}}"] = {{parameterName}}.toString()
+{{else}}
+        {{parameterName}}?.let { query["{{originalName}}"] = it.toString() }
 {{/if}}
-{{#each _queryParams}}
-        {{name}}: {{{kotlinType type}}}? = null,
 {{/each}}
-    ): {{{kotlinResponseType}}} {
-        val path = "{{path}}"
-
-        {{#if (hasQueryParams this)}}
-        val queryMap = mutableMapOf<String, String?>()
-        {{#each _queryParams}}
-        if ({{name}} != null) queryMap["{{originalName}}"] = {{name}}.toString()
-        {{/each}}
-        {{else}}
-        val queryMap: Map<String, String?>? = null
-        {{/if}}
-
-        {{#if (or (hasRequestBody this) (needsRequestHeaders this))}}
         val headers = mutableMapOf<String, String>()
-        {{#if (hasRequestBody this)}}
-        {{#if (and (neq requestBody.contentType "application/json") (neq requestBody.contentType "multipart/form-data"))}}
+{{#each headerParams}}
+{{#if required}}
+        headers["{{originalName}}"] = {{parameterName}}.toString()
+{{else}}
+        {{parameterName}}?.let { headers["{{originalName}}"] = it.toString() }
+{{/if}}
+{{/each}}
+{{#if cookieParams.length}}
+        val cookies = mutableListOf<String>()
+{{#each cookieParams}}
+{{#if required}}
+        cookies += "{{originalName}}=${{{parameterName}}}"
+{{else}}
+        {{parameterName}}?.let { cookies += "{{originalName}}=$it" }
+{{/if}}
+{{/each}}
+        if (cookies.isNotEmpty()) headers["Cookie"] = cookies.joinToString("; ")
+{{/if}}
+{{#if requestBody}}
+{{#if (and (neq requestBody.contentType "application/json") (neq requestBody.contentType "multipart/form-data"))}}
         headers["Content-Type"] = "{{requestBody.contentType}}"
-        {{/if}}
-        {{/if}}
-        {{#each headerParams}}
-        // TODO: inject header param '{{originalName}}' from header options
-        {{/each}}
-        {{else}}
-        val headers: Map<String, String>? = null
-        {{/if}}
+{{/if}}
+{{/if}}
 
-        return transport.execute<{{{kotlinResponseType}}}>(
+{{#if isEventStream}}
+        return transport.executeRaw(
+{{else}}
+        return transport.execute<{{{targetResponseType}}}>(
+{{/if}}
             method = HttpMethod.{{pascalCase httpMethod}},
             path = path,
-            query = queryMap,
-            body = {{#if requestBody}}body{{else}}null{{/if}},
-            headers = headers{{#unless (or (hasRequestBody this) (needsRequestHeaders this))}}{{/unless}},
+            query = query.ifEmpty { null },
+            body = {{{bodyExpression}}},
+            headers = headers.ifEmpty { null },
         )
     }
 

package/templates/kotlin/errors.hbs

@@ -28,7 +28,7 @@ class SdkException(
     fun isNetworkError(): Boolean = status == null
 
     /** Returns `true` if this error is retryable. */
-    fun isRetryable(): Boolean = isNetworkError() || status in setOf(429, 502, 503, 504)
+    fun isRetryable(): Boolean = isNetworkError() || status in setOf(408, 425, 429, 500, 502, 503, 504)
 
     override fun toString(): String {
         val sb = StringBuilder("SdkException(")

package/templates/kotlin/readme.hbs

@@ -1,168 +1,66 @@
-# {{title}}
+# {{title}} Kotlin SDK
 
-{{#if description}}{{description}}{{/if}}
+{{#if description}}{{description}}{{else}}Kotlin client for the {{title}} API.{{/if}}
 
-{{#unless description}}An auto-generated Kotlin SDK for the {{title}} API.{{/unless}}
+> Generated by Tesseract. Generated source files should not be edited manually.
 
 ## Installation
 
-### Gradle
-
-Add the dependency to your `build.gradle.kts`:
-
 ```kotlin
-repositories {
-    mavenCentral()
-    // If publishing to a private repository, add it here.
-}
-
 dependencies {
-    implementation("{{groupId}}:{{artifactId}}:{{#if packageVersion}}{{packageVersion}}{{else}}0.1.0{{/if}}")
+    implementation("{{groupId}}:{{artifactId}}:{{packageVersion}}")
 }
 ```
 
-### Maven
-
-```xml
-<dependency>
-    <groupId>{{groupId}}</groupId>
-    <artifactId>{{artifactId}}</artifactId>
-    <version>{{#if packageVersion}}{{packageVersion}}{{else}}0.1.0{{/if}}</version>
-</dependency>
-```
-
-## Publishing
-
-Publish to your local Maven cache:
-
-```bash
-gradle publishToMavenLocal
-```
-
-Publish to a Maven repository:
-
-```bash
-MAVEN_REPOSITORY_URL="https://maven.example.com/releases" \
-MAVEN_REPOSITORY_USERNAME="username" \
-MAVEN_REPOSITORY_PASSWORD="password" \
-gradle publish
-```
-
-The generated Gradle project also supports equivalent Gradle properties:
-
-- `mavenRepositoryUrl`
-- `mavenRepositoryUsername`
-- `mavenRepositoryPassword`
-- `mavenRepositoryName`
-
-For signed publications, provide `SIGNING_IN_MEMORY_KEY` and `SIGNING_IN_MEMORY_KEY_PASSWORD` or the matching Gradle properties `signingInMemoryKey` and `signingInMemoryKeyPassword`.
-
-For repositories that require richer POM metadata, set `POM_URL`, `POM_SCM_URL`, `POM_SCM_CONNECTION`, `POM_SCM_DEVELOPER_CONNECTION`, `POM_DEVELOPER_ID`, and `POM_DEVELOPER_NAME` or the equivalent lower-camel Gradle properties.
-
-## Quick Start
+## Quick start
 
 ```kotlin
-import {{packageName}}.Client
+import {{packageName}}.{{clientName}}Client
 import {{packageName}}.ClientConfig
-import kotlinx.coroutines.runBlocking
 
-fun main() = runBlocking {
-    val config = ClientConfig(
-{{#each securitySchemes}}
-{{#if (eq type "apiKey")}}
-        {{configKey}} = "your-api-key",
-{{/if}}
-{{#if (and (eq type "http") (eq scheme "bearer"))}}
-        {{configKey}} = "your-bearer-token",
-{{/if}}
-{{/each}}
+val client = {{clientName}}Client(
+    ClientConfig(
+        baseUrl = "{{baseUrl}}",
+        timeoutMs = 15_000,
     )
+)
 
-    val client = Client(config)
-
-{{#each groups}}
-{{#if @first}}
-    // val result = client.{{name}}.someOperation()
+{{#if groups.length}}
+val api = client.{{groups.[0].name}}
 {{/if}}
-{{/each}}
-}
 ```
 
-## API Reference
-
-{{#each groups}}
-### {{interfaceName}}
-
-{{#if description}}
-{{description}}
-{{/if}}
-
-| Method | HTTP | Description |
-|--------|------|-------------|
-{{#each operations}}
-| `{{name}}()` | `{{httpMethod}}` | {{#if summary}}{{summary}}{{else}}—{{/if}} |
-{{/each}}
-
-{{/each}}
+## Configuration and reliability
 
-## Error Handling
-
-All API methods throw `SdkException` on failure. The exception contains:
-
-- `status`: HTTP status code (for API errors)
-- `code`: Machine-readable error code (if available)
-- `message`: Human-readable error message
-- `requestId`: Server-assigned request ID for support
+The Ktor transport supports bounded request/connect/socket timeouts, coroutine cancellation, exponential-backoff retries, `Retry-After` handling, default headers, and structured `SdkException` values. Unsafe requests are not retried unless they are explicitly idempotent or unsafe retries are enabled.
 
 ```kotlin
-try {
-    val result = client.users.getUser("user-123")
-    println("Success: $result")
-} catch (e: SdkException) {
-    when {
-        e.isClientError() -> println("Bad request: ${e.message}")
-        e.isServerError() -> println("Server error (${e.status}): ${e.message}")
-        e.isNetworkError() -> println("Network error: ${e.message}")
-        else -> println("Error: ${e.message}")
-    }
-}
+val client = {{clientName}}Client(
+    ClientConfig(
+        timeoutMs = 30_000,
+        maxRetries = 3,
+    )
+)
 ```
 
-## Project Structure
+## Documentation
 
-```
-.
-├── build.gradle.kts               # Build configuration and dependencies
-├── settings.gradle.kts            # Project name
-├── gradle.properties              # Gradle JVM args and code style
-├── gradle/
-│   └── wrapper/
-│       └── gradle-wrapper.properties  # Gradle wrapper distribution config
-├── .gitignore
-└── src/
-    └── main/
-        └── kotlin/
-            └── {{pkgPath}}/
-                ├── Client.kt          # Entry point — {{clientName}}Client
-                ├── api/
+- [Documentation index](./docs/README.md)
+- [Generated types](./docs/types.md)
+
+| Domain | Description |
+|---|---|
 {{#each groups}}
-                │   {{#if @last}}└──{{else}}├──{{/if}} {{interfaceName}}.kt
+| [{{interfaceName}}](./docs/domains/{{fileName}}.md) | {{#if description}}{{description}}{{else}}{{name}} operations{{/if}} |
 {{/each}}
-                ├── exceptions/
-                │   └── SdkException.kt
-                ├── internal/
-                │   └── Transport.kt   # HTTP layer (Ktor CIO + retry logic)
-                └── models/
-                    └── Types.kt       # Generated data classes and enums
-```
 
-> **Note:** The Gradle Wrapper JAR (`gradle/wrapper/gradle-wrapper.jar`) and the
-> `gradlew` / `gradlew.bat` scripts are not generated. Run the following once
-> after cloning to populate them:
->
-> ```bash
-> gradle wrapper --gradle-version 9.5.1
-> ```
+## Error handling
+
+All operations throw `SdkException` on failure. It exposes `status`, `code`, `requestId`, and helpers for client, server, network, and retryable failures.
+
+## Requirements
+
+- JVM 17 or later
 
 ## License