@apollo-deploy/tesseract 0.9.1 → 1.0.0

package/templates/kotlin/errors.hbs

@@ -0,0 +1,42 @@
+package {{packageName}}
+
+/**
+ * Primary exception type for the {{packageName}} SDK.
+ *
+ * All API methods throw [SdkException] on failure.
+ */
+class SdkException(
+    /** HTTP status code, if this is an API error. */
+    val status: Int?,
+    /** Machine-readable error code (if available). */
+    val code: String?,
+    /** Human-readable error message. */
+    override val message: String,
+    /** Server-assigned request ID for support. */
+    val requestId: String?,
+    /** The underlying cause, if any. */
+    cause: Throwable? = null,
+) : Exception(message, cause) {
+
+    /** Returns `true` if this error was caused by the server (5xx). */
+    fun isServerError(): Boolean = status != null && status in 500..599
+
+    /** Returns `true` if this error was caused by the client (4xx). */
+    fun isClientError(): Boolean = status != null && status in 400..499
+
+    /** Returns `true` if this is a network error (should be retried safely). */
+    fun isNetworkError(): Boolean = status == null
+
+    /** Returns `true` if this error is retryable. */
+    fun isRetryable(): Boolean = isNetworkError() || status in setOf(429, 502, 503, 504)
+
+    override fun toString(): String {
+        val sb = StringBuilder("SdkException(")
+        if (status != null) sb.append("status=$status, ")
+        if (code != null) sb.append("code='$code', ")
+        sb.append("message='$message'")
+        if (requestId != null) sb.append(", requestId='$requestId'")
+        sb.append(")")
+        return sb.toString()
+    }
+}

package/templates/kotlin/gradle-properties.hbs

@@ -0,0 +1,2 @@
+kotlin.code.style=official
+org.gradle.jvmargs=-Xmx1g

package/templates/kotlin/readme.hbs

@@ -0,0 +1,105 @@
+# {{title}}
+
+{{#if description}}{{description}}{{/if}}
+
+{{#unless description}}An auto-generated Kotlin SDK for the {{title}} API.{{/unless}}
+
+## 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}}")
+}
+```
+
+### Maven
+
+```xml
+<dependency>
+    <groupId>{{groupId}}</groupId>
+    <artifactId>{{artifactId}}</artifactId>
+    <version>{{#if packageVersion}}{{packageVersion}}{{else}}0.1.0{{/if}}</version>
+</dependency>
+```
+
+## Quick Start
+
+```kotlin
+import {{packageName}}.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 = Client(config)
+
+{{#each groups}}
+{{#if @first}}
+    // val result = client.{{name}}.someOperation()
+{{/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}}
+
+## 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
+
+```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}")
+    }
+}
+```
+
+## License
+
+MIT

package/templates/kotlin/settings-gradle.hbs

@@ -0,0 +1 @@
+rootProject.name = "{{artifactId}}"

package/templates/kotlin/transport.hbs

@@ -0,0 +1,246 @@
+package {{packageName}}
+
+import io.ktor.client.*
+import io.ktor.client.engine.cio.*
+import io.ktor.client.plugins.*
+import io.ktor.client.plugins.contentnegotiation.*
+import io.ktor.client.request.*
+import io.ktor.client.statement.*
+import io.ktor.http.*
+import io.ktor.serialization.kotlinx.json.*
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.jsonPrimitive
+import kotlinx.coroutines.*
+
+/**
+ * Internal transport configuration.
+ */
+data class TransportConfig(
+    val baseUrl: String,
+{{#each securitySchemes}}
+    val {{configKey}}: String? = null,
+{{/each}}
+    val timeoutMs: Long = 15000,
+    val maxRetries: Int = 3,
+)
+
+/**
+ * HTTP transport layer for the SDK.
+ *
+ * Handles request building, authentication, retries, and error mapping
+ * using Ktor's HttpClient.
+ */
+class Transport(
+    private val config: TransportConfig
+) {
+    private val json = Json {
+        ignoreUnknownKeys = true
+        isLenient = true
+        encodeDefaults = true
+        coerceInputValues = true
+    }
+
+    private val client = HttpClient(CIO) {
+        install(ContentNegotiation) {
+            json(json)
+        }
+
+        install(HttpTimeout) {
+            requestTimeoutMillis = config.timeoutMs
+            connectTimeoutMillis = config.timeoutMs
+            socketTimeoutMillis = config.timeoutMs
+        }
+
+        defaultRequest {
+            url(config.baseUrl)
+            contentType(ContentType.Application.Json)
+            accept(ContentType.Application.Json)
+        }
+    }
+
+    /**
+     * Execute an HTTP request, deserializing the response body as JSON.
+     */
+    suspend inline fun <reified T> execute(
+        method: HttpMethod,
+        path: String,
+        query: Map<String, String?>? = null,
+        body: Any? = null,
+        headers: Map<String, String>? = null,
+    ): T {
+        val response = executeRaw(method, path, query, body, headers)
+        return json.decodeFromString<T>(response)
+    }
+
+    /**
+     * Execute an HTTP request, returning the raw response body as a string.
+     */
+    suspend fun executeRaw(
+        method: HttpMethod,
+        path: String,
+        query: Map<String, String?>? = null,
+        body: Any? = 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()
+    }
+
+    // ── private helpers ─────────────────────────────────────────────────────
+
+    @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)
+                        }
+                    }
+                }
+
+                // Set request body
+                if (body != null) {
+                    setBody(body)
+                }
+
+                // Set custom headers
+                headers?.forEach { (key, value) ->
+                    this.headers.append(key, value)
+                }
+
+                // Apply authentication
+                applyAuth()
+            }
+
+            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,
+                )
+            }
+        }
+    }
+
+    private suspend fun buildSdkException(response: HttpResponse): SdkException {
+        val status = response.status.value
+        val body = try {
+            response.bodyAsText()
+        } catch (e: Exception) {
+            null
+        }
+
+        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)"
+
+        if (body != null) {
+            try {
+                val jsonBody = json.decodeFromString<JsonObject>(body)
+                code = jsonBody["code"]?.jsonPrimitive?.content
+                    ?: jsonBody["error"]?.let { err ->
+                        when (err) {
+                            is JsonObject -> err["code"]?.jsonPrimitive?.content
+                            else -> err.jsonPrimitive?.content
+                        }
+                    }
+                message = jsonBody["message"]?.jsonPrimitive?.content
+                    ?: jsonBody["error"]?.let { err ->
+                        when (err) {
+                            is JsonObject -> err["message"]?.jsonPrimitive?.content
+                            else -> err.jsonPrimitive?.content
+                        }
+                    }
+                    ?: message
+            } catch (_: Exception) {
+                // Use raw body as the message
+                message = body
+            }
+        }
+
+        return SdkException(
+            status = status,
+            code = code,
+            message = message,
+            requestId = requestId,
+        )
+    }
+
+    private fun HttpRequestBuilder.applyAuth() {
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+{{#if (eq in "header")}}
+        config.{{configKey}}?.let { key ->
+            headers.append("{{paramName}}", key)
+        }
+{{/if}}
+{{#if (eq in "query")}}
+        // API key via query parameter handled during URL construction
+{{/if}}
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
+        config.{{configKey}}?.let { token ->
+            headers.append("Authorization", "Bearer $token")
+        }
+{{/if}}
+{{#if (eq type "oauth2")}}
+        config.{{configKey}}?.let { token ->
+            headers.append("Authorization", "Bearer $token")
+        }
+{{/if}}
+{{#if (eq type "openIdConnect")}}
+        config.{{configKey}}?.let { token ->
+            headers.append("Authorization", "Bearer $token")
+        }
+{{/if}}
+{{/each}}
+    }
+}

package/templates/kotlin/types.hbs

@@ -0,0 +1,100 @@
+package {{packageName}}
+
+import kotlinx.serialization.*
+import kotlinx.serialization.descriptors.*
+import kotlinx.serialization.encoding.*
+import kotlinx.serialization.json.*
+
+{{#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 isEnum}}
+{{#if description}}
+/**
+ * {{description}}
+ */
+{{/if}}
+@Serializable
+enum class {{name}} {
+    {{#each enumValues}}
+    @SerialName("{{this}}")
+    {{pascalCase this}},
+    {{/each}}
+}
+{{/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}}
+
+{{#if isIntersectionType}}
+{{#if intersectionMembers.length}}
+{{#if description}}
+/**
+ * {{description}}
+ */
+{{/if}}
+{{! Intersection type — emit as interface implemented by concrete types }}
+@Serializable
+data class {{name}}(
+    // Intersection of: {{join intersectionMembers ", "}}
+    // Fields from all intersected types should be inlined here.
+    // TODO: generate combined fields
+)
+{{/if}}
+{{/if}}
+
+{{/each}}

package/templates/php/client.hbs

@@ -0,0 +1,74 @@
+<?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}};
+{{/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>
+ */
+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
+     */
+    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;
+
+    /**
+     {{#if description}}
+     * {{description}}
+     *
+     {{/if}}
+     * @return {{className}}
+     */
+    public function {{name}}(): {{className}}
+    {
+        return $this->_{{{name}}} ??= new {{className}}($this->transport);
+    }
+
+    {{/each}}
+}

package/templates/php/composer.hbs

@@ -0,0 +1,19 @@
+{
+    "name": "{{composerName}}",
+    "description": "{{#if description}}{{description}}{{else}}PHP SDK for {{title}}{{/if}}",
+    "type": "library",
+    "license": "MIT",
+    "autoload": {
+        "psr-4": {
+            "{{namespace}}\\": "src/"
+        }
+    },
+    "require": {
+        "php": ">=8.1",
+        "guzzlehttp/guzzle": "^7.0",
+        "ext-json": "*"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^10.0"
+    }
+}