@apollo-deploy/tesseract 1.9.0 → 2.1.0

package/templates/kotlin/transport.hbs

@@ -9,34 +9,45 @@ import io.ktor.client.request.*
 import io.ktor.client.statement.*
 import io.ktor.http.*
 import io.ktor.serialization.kotlinx.json.*
+import java.time.ZonedDateTime
+import java.time.format.DateTimeFormatter
+import kotlin.math.max
+import kotlin.random.Random
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.delay
 import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
 import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.jsonPrimitive
-import kotlinx.coroutines.*
 
-/**
- * Internal transport configuration.
- */
+/** Internal transport configuration. */
 data class TransportConfig(
     val baseUrl: String,
 {{#each securitySchemes}}
     val {{configKey}}: String? = null,
 {{/each}}
     val defaultHeaders: Map<String, String> = emptyMap(),
-    val serviceToken: String? = null,
-    val timeoutMs: Long = 15000,
+    val timeoutMs: Long = 15_000,
     val maxRetries: Int = 3,
+    val retryUnsafeRequests: Boolean = false,
 )
 
 /**
  * HTTP transport layer for the SDK.
  *
- * Handles request building, authentication, retries, and error mapping
- * using Ktor's HttpClient.
+ * Retries transient failures for idempotent methods. POST and PATCH are retried
+ * only when [TransportConfig.retryUnsafeRequests] is enabled or an
+ * `X-Idempotency-Key` header is present.
  */
 class Transport(
-    private val config: TransportConfig
-) {
+    private val config: TransportConfig,
+) : AutoCloseable {
+    init {
+        require(config.baseUrl.isNotBlank()) { "baseUrl must not be blank" }
+        require(config.timeoutMs > 0) { "timeoutMs must be greater than zero" }
+        require(config.maxRetries >= 0) { "maxRetries must not be negative" }
+    }
+
     @PublishedApi
     internal val json = Json {
         ignoreUnknownKeys = true
@@ -58,8 +69,10 @@ class Transport(
 
         defaultRequest {
             url(config.baseUrl)
-            contentType(ContentType.Application.Json)
             accept(ContentType.Application.Json)
+            if (config.defaultHeaders.keys.none { it.equals(HttpHeaders.UserAgent, ignoreCase = true) }) {
+                header(HttpHeaders.UserAgent, "{{packageName}}/{{packageVersion}}")
+            }
 {{#each securitySchemes}}
 {{#if (eq type "apiKey")}}
 {{#if (eq in "header")}}
@@ -67,169 +80,173 @@ class Transport(
 {{/if}}
 {{/if}}
 {{#if (and (eq type "http") (eq scheme "bearer"))}}
-            config.{{configKey}}?.let { token -> headers.append("Authorization", "Bearer $token") }
+            config.{{configKey}}?.let { token -> headers.append(HttpHeaders.Authorization, "Bearer $token") }
 {{/if}}
 {{#if (eq type "oauth2")}}
-            config.{{configKey}}?.let { token -> headers.append("Authorization", "Bearer $token") }
+            config.{{configKey}}?.let { token -> headers.append(HttpHeaders.Authorization, "Bearer $token") }
 {{/if}}
 {{#if (eq type "openIdConnect")}}
-            config.{{configKey}}?.let { token -> headers.append("Authorization", "Bearer $token") }
+            config.{{configKey}}?.let { token -> headers.append(HttpHeaders.Authorization, "Bearer $token") }
 {{/if}}
 {{/each}}
-            config.defaultHeaders.forEach { (k, v) -> headers.append(k, v) }
+            config.defaultHeaders.forEach { (key, value) -> headers.append(key, value) }
         }
     }
 
-    /**
-     * Execute an HTTP request, deserializing the response body as JSON.
-     */
+    /** Execute an HTTP request and deserialize its JSON response. */
     suspend inline fun <reified T> execute(
         method: HttpMethod,
         path: String,
         query: Map<String, String?>? = null,
-        body: Any? = null,
+        body: JsonElement? = null,
         headers: Map<String, String>? = null,
     ): T {
         val response = executeRaw(method, path, query, body, headers)
+        if (response.isBlank()) {
+            @Suppress("UNCHECKED_CAST")
+            return Unit as T
+        }
         return json.decodeFromString<T>(response)
     }
 
-    /**
-     * Execute an HTTP request, returning the raw response body as a string.
-     */
+    /** Execute an HTTP request and return its raw response body. */
     suspend fun executeRaw(
         method: HttpMethod,
         path: String,
         query: Map<String, String?>? = null,
-        body: Any? = null,
+        body: JsonElement? = null,
         headers: Map<String, String>? = null,
     ): String {
-        return executeWithRetry(method, path, query, body, headers)
-    }
-
-    /**
-     * Close the underlying HTTP client. Call this when the SDK is no longer needed.
-     */
-    fun close() {
-        client.close()
-    }
+        val canRetry = canRetry(method, headers)
+        var lastError: Throwable? = null
 
-    // ── private helpers ─────────────────────────────────────────────────────
+        for (attempt in 0..config.maxRetries) {
+            try {
+                val response = client.request {
+                    this.method = method
+                    url {
+                        takeFrom("${config.baseUrl.trimEnd('/')}$path")
+                        query?.forEach { (key, value) ->
+                            value?.let { parameters.append(key, it) }
+                        }
+                    }
 
-    @OptIn(ExperimentalCoroutinesApi::class)
-    private suspend fun executeWithRetry(
-        method: HttpMethod,
-        path: String,
-        query: Map<String, String?>? = null,
-        body: Any? = null,
-        headers: Map<String, String>? = null,
-        attempt: Int = 0,
-    ): String {
-        return try {
-            val response = client.request {
-                this.method = method
-                url {
-                    // Base URL is set as default; append the path
-                    val fullUrl = "${config.baseUrl.trimEnd('/')}${path}"
-                    takeFrom(fullUrl)
-
-                    // Add query parameters
-                    query?.forEach { (key, value) ->
-                        if (value != null) {
-                            parameters.append(key, value)
+                    if (body != null) {
+                        if (headers?.keys?.none { it.equals(HttpHeaders.ContentType, ignoreCase = true) } != false) {
+                            contentType(ContentType.Application.Json)
                         }
+                        setBody(body)
                     }
+
+                    headers?.forEach { (key, value) -> this.headers.append(key, value) }
                 }
 
-                // Set request body
-                if (body != null) {
-                    setBody(body)
+                if (response.status.value in 200..299) {
+                    return response.bodyAsText()
                 }
 
-                // Set custom headers
-                headers?.forEach { (key, value) ->
-                    this.headers.append(key, value)
+                val error = buildSdkException(response)
+                if (!canRetry || !isRetryableStatus(response.status.value) || attempt == config.maxRetries) {
+                    throw error
                 }
-            }
 
-            val status = response.status.value
-
-            if (status in 200..299) {
-                response.bodyAsText()
-            } else if ((status >= 500 || status == 429) && attempt < config.maxRetries) {
-                // Retry on server errors and rate limiting
-                val backoffMs = 200L * (1L shl attempt)
-                delay(backoffMs)
-                executeWithRetry(method, path, query, body, headers, attempt + 1)
-            } else {
-                throw buildSdkException(response)
-            }
-        } catch (e: SdkException) {
-            throw e
-        } catch (e: CancellationException) {
-            throw e
-        } catch (e: Exception) {
-            if (attempt < config.maxRetries) {
-                val backoffMs = 200L * (1L shl attempt)
-                delay(backoffMs)
-                executeWithRetry(method, path, query, body, headers, attempt + 1)
-            } else {
-                throw SdkException(
-                    status = null,
-                    code = null,
-                    message = "Network error: ${e.message}",
-                    requestId = null,
-                    cause = e,
-                )
+                lastError = error
+                delay(retryDelayMs(response.headers[HttpHeaders.RetryAfter], attempt))
+            } catch (error: CancellationException) {
+                throw error
+            } catch (error: SdkException) {
+                throw error
+            } catch (error: Exception) {
+                if (!canRetry || attempt == config.maxRetries) {
+                    throw SdkException(
+                        status = null,
+                        code = null,
+                        message = "Network error: ${error.message ?: error::class.simpleName}",
+                        requestId = null,
+                        cause = error,
+                    )
+                }
+
+                lastError = error
+                delay(retryDelayMs(null, attempt))
             }
         }
+
+        throw SdkException(
+            status = null,
+            code = null,
+            message = "Request failed after ${config.maxRetries + 1} attempts",
+            requestId = null,
+            cause = lastError,
+        )
     }
 
-    private suspend fun buildSdkException(response: HttpResponse): SdkException {
-        val status = response.status.value
-        val body = try {
-            response.bodyAsText()
-        } catch (e: Exception) {
-            null
+    override fun close() {
+        client.close()
+    }
+
+    private fun canRetry(method: HttpMethod, headers: Map<String, String>?): Boolean {
+        if (config.retryUnsafeRequests || method in RETRYABLE_METHODS) return true
+        return config.defaultHeaders.any { (name, value) ->
+            name.equals("X-Idempotency-Key", ignoreCase = true) && value.isNotEmpty()
+        } || headers?.any { (name, value) ->
+            name.equals("X-Idempotency-Key", ignoreCase = true) && value.isNotEmpty()
+        } == true
+    }
+
+    private fun retryDelayMs(retryAfter: String?, attempt: Int): Long {
+        val serverDelay = retryAfter?.trim()?.let { value ->
+            value.toLongOrNull()?.let { seconds -> max(0L, seconds * 1_000L) }
+                ?: runCatching {
+                    max(
+                        0L,
+                        ZonedDateTime.parse(value, DateTimeFormatter.RFC_1123_DATE_TIME)
+                            .toInstant()
+                            .toEpochMilli() - System.currentTimeMillis(),
+                    )
+                }.getOrNull()
         }
+        if (serverDelay != null) return serverDelay.coerceAtMost(MAX_RETRY_DELAY_MS)
+
+        val base = (200L * (1L shl attempt.coerceAtMost(10))).coerceAtMost(MAX_RETRY_DELAY_MS)
+        return (base + Random.nextLong(base / 2 + 1)).coerceAtMost(MAX_RETRY_DELAY_MS)
+    }
 
-        val requestId = response.headers["x-request-id"]
-            ?: response.headers["request-id"]
+    private suspend fun buildSdkException(response: HttpResponse): SdkException {
+        val status = response.status.value
+        val body = runCatching { response.bodyAsText() }.getOrNull()
+        val requestId = response.headers["x-request-id"] ?: response.headers["request-id"]
 
-        // Try to extract structured error info from the JSON body
         var code: String? = null
-        var message: String = body ?: "API error (status $status)"
+        var message = body?.takeIf { it.isNotBlank() } ?: "API error (status $status)"
 
-        if (body != null) {
-            try {
+        if (!body.isNullOrBlank()) {
+            runCatching {
                 val jsonBody = json.decodeFromString<JsonObject>(body)
+                val error = jsonBody["error"]
                 code = jsonBody["code"]?.jsonPrimitive?.content
-                    ?: jsonBody["error"]?.let { err ->
-                        when (err) {
-                            is JsonObject -> err["code"]?.jsonPrimitive?.content
-                            else -> err.jsonPrimitive.content
-                        }
-                    }
+                    ?: (error as? JsonObject)?.get("code")?.jsonPrimitive?.content
                 message = jsonBody["message"]?.jsonPrimitive?.content
-                    ?: jsonBody["error"]?.let { err ->
-                        when (err) {
-                            is JsonObject -> err["message"]?.jsonPrimitive?.content
-                            else -> err.jsonPrimitive.content
-                        }
-                    }
+                    ?: (error as? JsonObject)?.get("message")?.jsonPrimitive?.content
+                    ?: error?.jsonPrimitive?.content
                     ?: message
-            } catch (_: Exception) {
-                // Use raw body as the message
-                message = body
             }
         }
 
-        return SdkException(
-            status = status,
-            code = code,
-            message = message,
-            requestId = requestId,
-        )
+        return SdkException(status, code, message, requestId)
     }
 
+    private companion object {
+        val RETRYABLE_METHODS = setOf(
+            HttpMethod.Get,
+            HttpMethod.Head,
+            HttpMethod.Options,
+            HttpMethod.Put,
+            HttpMethod.Delete,
+        )
+        val RETRYABLE_STATUSES = setOf(408, 425, 429, 500, 502, 503, 504)
+        const val MAX_RETRY_DELAY_MS = 30_000L
+
+        fun isRetryableStatus(status: Int): Boolean = status in RETRYABLE_STATUSES
+    }
 }

package/templates/kotlin/types.hbs

@@ -1,100 +1,49 @@
 package {{packageName}}.models
 
-import kotlinx.serialization.*
-import kotlinx.serialization.descriptors.*
-import kotlinx.serialization.encoding.*
-import kotlinx.serialization.json.*
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonElement
 
 {{#each schemas}}
-{{#if (not ownership)}}
-{{#unless (or externalImport (eq ownership.kind "external"))}}
-{{#if (not isEnum)}}
-{{#if (not isUnionType)}}
-{{#if (not isIntersectionType)}}
-{{#if (not isTypeAlias)}}
-{{#if description}}
-/**
- * {{description}}
- */
-{{/if}}
-@Serializable
-data class {{name}}(
-    {{#each properties}}
-    {{#if description}}
-    /** {{description}} */
-    {{/if}}
-    {{#if deprecated}}
-    @Deprecated("{{#if deprecationMessage}}{{deprecationMessage}}{{else}}Use a different property.{{/if}}")
-    {{/if}}
-    {{#if (and nullable (not required))}}
-    @SerialName("{{name}}")
-    val {{name}}: {{{kotlinType type}}}? = null,
-    {{else if nullable}}
-    @SerialName("{{name}}")
-    val {{name}}: {{{kotlinType type}}}? = null,
-    {{else if required}}
-    @SerialName("{{name}}")
-    val {{name}}: {{{kotlinType type}}},
-    {{else}}
-    @SerialName("{{name}}")
-    val {{name}}: {{{kotlinType type}}}? = null,
-    {{/if}}
-    {{/each}}
-)
-{{/if}}
-{{/if}}
-{{/if}}
-{{/if}}
-{{/unless}}
-{{/if}}
+{{#if external}}
+typealias {{name}} = JsonElement
 
-{{#if isEnum}}
-{{#if description}}
-/**
- * {{description}}
- */
-{{/if}}
+{{else if isEnum}}
+{{#if stringEnum}}
 @Serializable
 enum class {{name}} {
-    {{#each enumValues}}
-    @SerialName("{{this}}")
-    {{pascalCase this}},
-    {{/each}}
+{{#each enumValues}}
+    @SerialName("{{value}}") {{name}},
+{{/each}}
 }
+{{else}}
+typealias {{name}} = Double
 {{/if}}
 
-{{#if isUnionType}}
-{{#if unionMembers.length}}
-{{#if description}}
-/**
- * {{description}}
- */
-{{/if}}
-@Serializable
-sealed class {{name}} {
-    {{#each unionMembers}}
-    @Serializable
-    data class {{pascalCase this}}(val value: {{{kotlinType this}}}) : {{../name}}()
-    {{/each}}
-}
-{{/if}}
-{{/if}}
+{{else if isUnionType}}
+typealias {{name}} = JsonElement
+
+{{else if isIntersectionType}}
+typealias {{name}} = JsonElement
 
-{{#if isIntersectionType}}
-{{#if intersectionMembers.length}}
+{{else if isTypeAlias}}
+typealias {{name}} = {{{aliasType}}}
+
+{{else}}
 {{#if description}}
-/**
- * {{description}}
- */
+/** {{description}} */
 {{/if}}
-{{! Intersection type — emit as interface implemented by concrete types }}
 @Serializable
+{{#if hasProperties}}
 data class {{name}}(
-    // Intersection of: {{join intersectionMembers ", "}}
-    // Fields from all intersected types should be inlined here.
-    // TODO: generate combined fields
+{{#each properties}}
+    @SerialName("{{name}}")
+    val {{fieldName}}: {{{targetType}}}{{#if hasDefault}} = null{{/if}},
+{{/each}}
 )
-{{/if}}
+{{else}}
+class {{name}}
 {{/if}}
 
+{{/if}}
 {{/each}}

package/templates/php/client.hbs

@@ -1,74 +1,36 @@
 <?php
 
-/**
- * @generated
- * This file was automatically generated by Tesseract.
- * DO NOT MODIFY THIS FILE DIRECTLY.
- */
-
 declare(strict_types=1);
 
 namespace {{namespace}};
 
 {{#each groups}}
-use {{namespace}}\Api\{{className}};
+use {{fullClassName}};
 {{/each}}
 
-/**
- * {{title}} SDK Client.
- *
- * Entry point for all API operations. Provides accessor methods
- * for each domain group and manages shared transport configuration.
- *
- * Usage:
- * <code>
- * $client = new Client(['baseUrl' => '{{baseUrl}}']);
- * $result = $client->{{groups.[0].name}}()->{{groups.[0].operations.[0].name}}(...);
- * </code>
- */
+/** {{title}} SDK client. */
 class Client
 {
     private Transport $transport;
 
-    /**
-     * @param array{
-     *     baseUrl?: string,
-     *     timeoutMs?: int,
-     *     retries?: array{attempts?: int, backoffMs?: int, jitter?: bool, maxBackoffMs?: int},
-     *     defaultHeaders?: array<string, string>,
-     {{#each securitySchemes}}
-     *     {{configKey}}?: string,
-     {{/each}}
-     * } $config
-     */
+    /** @param array<string, mixed> $config */
     public function __construct(array $config = [])
     {
         $this->transport = new Transport($config);
     }
 
-    /**
-     * Get the underlying transport instance for advanced use.
-     */
     public function getTransport(): Transport
     {
         return $this->transport;
     }
 
-    {{#each groups}}
-    /** @var {{className}}|null */
-    private ?{{className}} $_{{{name}}} = null;
+{{#each groups}}
+    private ?{{className}} $_{{accessorName}} = null;
 
-    /**
-     {{#if description}}
-     * {{description}}
-     *
-     {{/if}}
-     * @return {{className}}
-     */
-    public function {{name}}(): {{className}}
+    public function {{accessorName}}(): {{className}}
     {
-        return $this->_{{{name}}} ??= new {{className}}($this->transport);
+        return $this->_{{accessorName}} ??= new {{className}}($this->transport);
     }
 
-    {{/each}}
+{{/each}}
 }

package/templates/php/composer.hbs

@@ -6,7 +6,8 @@
     "autoload": {
         "psr-4": {
             "{{namespace}}\\": "src/"
-        }
+        },
+        "classmap": ["src/Types.php"]
     },
     "require": {
         "php": ">=8.1",