@apollo-deploy/tesseract 0.9.1 → 1.2.0

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"
+    }
+}

package/templates/php/domain.hbs

@@ -0,0 +1,173 @@
+<?php
+
+/**
+ * @generated
+ * This file was automatically generated by Tesseract.
+ * DO NOT MODIFY THIS FILE DIRECTLY.
+ */
+
+declare(strict_types=1);
+
+namespace {{namespace}}\Api;
+
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * {{interfaceName}} domain operations.
+ *
+{{#if description}}
+ * {{description}}
+ *
+{{/if}}
+ * @generated
+ */
+class {{className}}
+{
+    private Transport $transport;
+
+    public function __construct(Transport $transport)
+    {
+        $this->transport = $transport;
+    }
+
+{{#each operations}}
+{{#if (isEventStream this)}}
+    // SSE operations are not yet supported in the PHP adapter — skipping {{name}}
+
+{{else}}
+    /**
+     {{#if deprecated}}
+     * @deprecated{{#if deprecationMessage}} {{deprecationMessage}}{{/if}}
+     *
+     {{/if}}
+     {{#if (or summary description)}}
+     * {{#if summary}}{{summary}}{{#if description}} — {{description}}{{/if}}{{else}}{{description}}{{/if}}
+     *
+     {{/if}}
+     {{#each pathParams}}
+     * @param {{type}} ${{name}}{{#if description}} {{description}}{{/if}}
+     {{/each}}
+     {{#if requestBody}}
+     * @param array<string, mixed>{{#unless requestBody.required}}|null{{/unless}} $input Request body
+     {{/if}}
+     {{#each queryParams}}
+     * @param {{type}}|null ${{name}}{{#if description}} {{description}}{{/if}}
+     {{/each}}
+     {{#each headerParams}}
+     * @param {{type}}|null ${{name}}{{#if description}} {{description}}{{/if}}
+     {{/each}}
+     * @return {{responseType}}
+     * @throws SDKError
+     */
+    public function {{name}}(
+        {{#each pathParams}}
+        {{type}} ${{name}},
+        {{/each}}
+        {{#if requestBody}}
+        {{#unless requestBody.required}}?{{/unless}}array $input{{#unless requestBody.required}} = null{{/unless}},
+        {{/if}}
+        {{#each queryParams}}
+        ?{{type}} ${{name}} = null,
+        {{/each}}
+        {{#each headerParams}}
+        ?{{type}} ${{name}} = null,
+        {{/each}}
+    ): {{responseType}}
+    {
+        // Build path with parameter substitution
+        $path = '{{path}}';
+        {{#if (hasPathParams this)}}
+        $path = str_replace(
+            [{{#each pathParams}}'{{@root.LBRACE}}{{originalName}}{{@root.RBRACE}}'{{#unless @last}}, {{/unless}}{{/each}}],
+            [{{#each pathParams}}${{name}}{{#unless @last}}, {{/unless}}{{/each}}],
+            $path
+        );
+        {{/if}}
+
+        // Build query parameters
+        $query = [];
+        {{#if (hasQueryParams this)}}
+        {{#each queryParams}}
+        if (${{name}} !== null) {
+            $query['{{originalName}}'] = ${{name}};
+        }
+        {{/each}}
+        {{/if}}
+
+        // Build extra headers
+        $headers = [];
+        {{#each headerParams}}
+        if (${{name}} !== null) {
+            $headers['{{originalName}}'] = (string) ${{name}};
+        }
+        {{/each}}
+
+        // Execute request
+        $requestDef = [
+            'method' => '{{httpMethod}}',
+            'path' => $path,
+            'query' => $query,
+            'headers' => $headers,
+        ];
+
+        {{#if (hasRequestBody this)}}
+        if ($input !== null) {
+            $requestDef['body'] = $input;
+        }
+        {{/if}}
+
+        $response = $this->transport->executeRequest($requestDef);
+
+        // Deserialize response
+        $data = $this->decodeResponse($response);
+
+        {{#if (eq responseType "void")}}
+        return;
+        {{else if (eq responseType "string")}}
+        return (string) $data;
+        {{else if (eq responseType "int")}}
+        return (int) $data;
+        {{else if (eq responseType "float")}}
+        return (float) $data;
+        {{else if (eq responseType "bool")}}
+        return (bool) $data;
+        {{else if (eq responseType "array")}}
+        return $data;
+        {{else}}
+        // Complex type: deserialize via fromArray
+        if (class_exists({{responseType}}::class) && method_exists({{responseType}}::class, 'fromArray')) {
+            return {{responseType}}::fromArray($data);
+        }
+        return $data;
+        {{/if}}
+    }
+
+{{/if}}
+{{/each}}
+
+    /**
+     * Decode a PSR-7 response body to an associative array or raw value.
+     *
+     * @return array<string, mixed>|string
+     */
+    private function decodeResponse(ResponseInterface $response): array|string
+    {
+        $contents = $response->getBody()->__toString();
+
+        try {
+            $decoded = json_decode($contents, true, 512, JSON_THROW_ON_ERROR);
+            if (is_array($decoded)) {
+                return $decoded;
+            }
+            if (is_scalar($decoded)) {
+                return (string) $decoded;
+            }
+            return ['raw' => $decoded];
+        } catch (\JsonException) {
+            if (trim($contents) === '') {
+                return [];
+            }
+            return $contents;
+        }
+    }
+}