@apollo-deploy/tesseract 0.9.0 → 1.0.0

package/templates/csharp/transport.hbs

@@ -0,0 +1,291 @@
+namespace {{namespace}};
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Net.Http;
+using System.Text;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+
+/// <summary>
+/// Configuration for the HTTP transport layer.
+/// </summary>
+public class TransportConfig
+{
+    public string BaseUrl { get; set; } = "";
+{{#each securitySchemes}}
+    public string? {{pascalCase configKey}} { get; set; }
+{{/each}}
+    public int TimeoutMs { get; set; } = 15000;
+    public int MaxRetries { get; set; } = 3;
+    public Dictionary<string, string>? DefaultHeaders { get; set; }
+}
+
+/// <summary>
+/// Low-level HTTP transport handling authentication, serialization, retries, and error normalization.
+/// </summary>
+public class Transport
+{
+    private readonly TransportConfig _config;
+    private readonly HttpClient _httpClient;
+    private static readonly JsonSerializerOptions _jsonOptions = new()
+    {
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        PropertyNameCaseInsensitive = true,
+        DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull,
+    };
+
+    public Transport(TransportConfig config)
+    {
+        _config = config;
+        _httpClient = new HttpClient
+        {
+            Timeout = TimeSpan.FromMilliseconds(config.TimeoutMs),
+        };
+    }
+
+    public class Request
+    {
+        public HttpMethod Method { get; set; } = HttpMethod.Get;
+        public string Path { get; set; } = "";
+        public Dictionary<string, string>? Query { get; set; }
+        public object? Body { get; set; }
+        public string? ContentType { get; set; }
+        public Dictionary<string, string>? Headers { get; set; }
+    }
+
+    public async Task<T> ExecuteAsync<T>(Request request, CancellationToken cancellationToken = default)
+    {
+        return await ExecuteWithRetriesAsync<T>(request, _config.MaxRetries, cancellationToken);
+    }
+
+    public async Task<byte[]> ExecuteRawAsync(Request request, CancellationToken cancellationToken = default)
+    {
+        return await ExecuteRawWithRetriesAsync(request, _config.MaxRetries, cancellationToken);
+    }
+
+    public async Task<HttpResponseMessage> StreamAsync(Request request, CancellationToken cancellationToken = default)
+    {
+        using var httpRequest = BuildRequest(request);
+        var response = await _httpClient.SendAsync(
+            httpRequest,
+            HttpCompletionOption.ResponseHeadersRead,
+            cancellationToken);
+        if (!response.IsSuccessStatusCode)
+        {
+            var errorBody = await response.Content.ReadAsStringAsync(cancellationToken);
+            throw ParseErrorResponse(response, errorBody);
+        }
+        return response;
+    }
+
+    private async Task<T> ExecuteWithRetriesAsync<T>(
+        Request request, int maxRetries, CancellationToken cancellationToken)
+    {
+        Exception? lastException = null;
+        for (int attempt = 0; attempt <= maxRetries; attempt++)
+        {
+            if (attempt > 0)
+            {
+                var backoff = (int)Math.Pow(2, attempt - 1) * 200;
+                var jitter = Random.Shared.Next(backoff / 2);
+                await Task.Delay(backoff + jitter, cancellationToken);
+            }
+            try
+            {
+                using var httpRequest = BuildRequest(request);
+                using var response = await _httpClient.SendAsync(httpRequest, cancellationToken);
+                var body = await response.Content.ReadAsStringAsync(cancellationToken);
+                if (response.IsSuccessStatusCode)
+                {
+                    if (string.IsNullOrEmpty(body)) return default!;
+                    var result = JsonSerializer.Deserialize<T>(body, _jsonOptions);
+                    if (result == null)
+                        throw new SdkException((int)response.StatusCode, "DESERIALIZE_ERROR",
+                            "Failed to deserialize response body", GetRequestId(response));
+                    return result;
+                }
+                if ((int)response.StatusCode >= 500 && attempt < maxRetries)
+                {
+                    lastException = ParseErrorResponse(response, body);
+                    continue;
+                }
+                throw ParseErrorResponse(response, body);
+            }
+            catch (SdkException) { throw; }
+            catch (TaskCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }
+            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }
+            catch (Exception ex) when (IsRetryable(ex) && attempt < maxRetries) { lastException = ex; }
+            catch (Exception ex)
+            {
+                throw new SdkException(0, "REQUEST_ERROR", ex.Message, null, ex);
+            }
+        }
+        throw new SdkException(0, "MAX_RETRIES_EXCEEDED",
+            "Request failed after " + (maxRetries + 1) + " attempts", null, lastException);
+    }
+
+    private async Task<byte[]> ExecuteRawWithRetriesAsync(
+        Request request, int maxRetries, CancellationToken cancellationToken)
+    {
+        Exception? lastException = null;
+        for (int attempt = 0; attempt <= maxRetries; attempt++)
+        {
+            if (attempt > 0)
+            {
+                var backoff = (int)Math.Pow(2, attempt - 1) * 200;
+                var jitter = Random.Shared.Next(backoff / 2);
+                await Task.Delay(backoff + jitter, cancellationToken);
+            }
+            try
+            {
+                using var httpRequest = BuildRequest(request);
+                using var response = await _httpClient.SendAsync(httpRequest, cancellationToken);
+                var body = await response.Content.ReadAsByteArrayAsync(cancellationToken);
+                if (response.IsSuccessStatusCode) return body;
+                var bodyString = Encoding.UTF8.GetString(body);
+                if ((int)response.StatusCode >= 500 && attempt < maxRetries)
+                {
+                    lastException = ParseErrorResponse(response, bodyString);
+                    continue;
+                }
+                throw ParseErrorResponse(response, bodyString);
+            }
+            catch (SdkException) { throw; }
+            catch (TaskCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }
+            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }
+            catch (Exception ex) when (IsRetryable(ex) && attempt < maxRetries) { lastException = ex; }
+            catch (Exception ex)
+            {
+                throw new SdkException(0, "REQUEST_ERROR", ex.Message, null, ex);
+            }
+        }
+        throw new SdkException(0, "MAX_RETRIES_EXCEEDED",
+            "Request failed after " + (maxRetries + 1) + " attempts", null, lastException);
+    }
+
+    private HttpRequestMessage BuildRequest(Request request)
+    {
+        var baseUri = new Uri(_config.BaseUrl.TrimEnd('/') + "/");
+        var fullUri = new Uri(baseUri, request.Path.TrimStart('/'));
+
+        if (request.Query?.Count > 0)
+        {
+            var queryString = string.Join("&",
+                request.Query.Select(kv =>
+                    Uri.EscapeDataString(kv.Key) + "=" + Uri.EscapeDataString(kv.Value)));
+            var separator = fullUri.Query.Length > 0 ? "&" : "";
+            fullUri = new Uri(fullUri, fullUri.PathAndQuery + separator + queryString);
+        }
+
+        var httpRequest = new HttpRequestMessage(request.Method, fullUri);
+
+        if (_config.DefaultHeaders != null)
+        {
+            foreach (var (key, value) in _config.DefaultHeaders)
+            {
+                httpRequest.Headers.TryAddWithoutValidation(key, value);
+            }
+        }
+
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+{{#if (eq in "header")}}
+        if (!string.IsNullOrEmpty(_config.{{pascalCase configKey}}))
+            httpRequest.Headers.TryAddWithoutValidation("{{paramName}}", _config.{{pascalCase configKey}});
+{{/if}}
+{{#if (eq in "query")}}
+        if (!string.IsNullOrEmpty(_config.{{pascalCase configKey}}))
+        {
+            var sep = fullUri.Query.Length > 0 ? "&" : "";
+            fullUri = new Uri(fullUri, fullUri.PathAndQuery + sep + "{{paramName}}=" + Uri.EscapeDataString(_config.{{pascalCase configKey}}));
+            httpRequest.RequestUri = fullUri;
+        }
+{{/if}}
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
+        if (!string.IsNullOrEmpty(_config.{{pascalCase configKey}}))
+            httpRequest.Headers.TryAddWithoutValidation("Authorization", "Bearer " + _config.{{pascalCase configKey}});
+{{/if}}
+{{#if (eq type "oauth2")}}
+        if (!string.IsNullOrEmpty(_config.{{pascalCase configKey}}))
+            httpRequest.Headers.TryAddWithoutValidation("Authorization", "Bearer " + _config.{{pascalCase configKey}});
+{{/if}}
+{{#if (eq type "openIdConnect")}}
+        if (!string.IsNullOrEmpty(_config.{{pascalCase configKey}}))
+            httpRequest.Headers.TryAddWithoutValidation("Authorization", "Bearer " + _config.{{pascalCase configKey}});
+{{/if}}
+{{/each}}
+
+        if (request.Body != null)
+        {
+            var contentType = request.ContentType ?? "application/json";
+            var json = JsonSerializer.Serialize(request.Body, _jsonOptions);
+            httpRequest.Content = new StringContent(json, Encoding.UTF8, contentType);
+        }
+
+        if (request.Headers != null)
+        {
+            foreach (var (key, value) in request.Headers)
+            {
+                if (key.Equals("Content-Type", StringComparison.OrdinalIgnoreCase) && httpRequest.Content != null)
+                {
+                    httpRequest.Content.Headers.ContentType =
+                        new System.Net.Http.Headers.MediaTypeHeaderValue(value);
+                }
+                else
+                {
+                    httpRequest.Headers.TryAddWithoutValidation(key, value);
+                }
+            }
+        }
+
+        return httpRequest;
+    }
+
+    private static bool IsRetryable(Exception ex)
+    {
+        return ex is HttpRequestException ||
+               ex is TaskCanceledException ||
+               ex is IOException ||
+               ex.Message.Contains("connection") ||
+               ex.Message.Contains("timeout") ||
+               ex.Message.Contains("reset");
+    }
+
+    private static SdkException ParseErrorResponse(HttpResponseMessage response, string body)
+    {
+        var requestId = GetRequestId(response);
+        try
+        {
+            using var doc = JsonDocument.Parse(body);
+            var root = doc.RootElement;
+            var code = "";
+            var message = "";
+            if (root.TryGetProperty("code", out var codeEl)) code = codeEl.GetString() ?? "";
+            if (root.TryGetProperty("message", out var msgEl)) message = msgEl.GetString() ?? "";
+            else if (root.TryGetProperty("error", out var errEl)) message = errEl.GetString() ?? "";
+            if (string.IsNullOrEmpty(message)) message = body.Trim();
+            return new SdkException((int)response.StatusCode, code, message, requestId);
+        }
+        catch (JsonException)
+        {
+            return new SdkException((int)response.StatusCode, "",
+                string.IsNullOrWhiteSpace(body)
+                    ? "HTTP " + (int)response.StatusCode + ": " + response.ReasonPhrase
+                    : body.Trim(), requestId);
+        }
+    }
+
+    private static string? GetRequestId(HttpResponseMessage response)
+    {
+        if (response.Headers.TryGetValues("X-Request-ID", out var values))
+            return values.FirstOrDefault();
+        if (response.Headers.TryGetValues("x-request-id", out values))
+            return values.FirstOrDefault();
+        return null;
+    }
+}

package/templates/csharp/types.hbs

@@ -0,0 +1,104 @@
+namespace {{namespace}};
+
+using System;
+using System.Collections.Generic;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+{{#each schemas}}
+{{#if (neq ownership.kind "external")}}
+{{#if isEnum}}
+/// <summary>
+{{#if description}}
+/// {{description}}
+{{else}}
+/// {{name}} enumeration.
+{{/if}}
+/// </summary>
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum {{name}}
+{
+{{#each enumValues}}
+    /// <summary>
+    /// {{this}} value.
+    /// </summary>
+    [JsonStringEnumMemberName("{{this}}")]
+    {{pascalCase ../name}}{{pascalCase this}},
+{{/each}}
+}
+
+{{else if isUnionType}}
+/// <summary>
+{{#if description}}
+/// {{description}}
+{{else}}
+/// {{name}} union type.
+{{/if}}
+/// </summary>
+public class {{name}}
+{
+    private readonly object _value;
+    private readonly Type _type;
+
+{{#each unionMembers}}
+    /// <summary>
+    /// Creates a {{../name}} from a {{this}} value.
+    /// </summary>
+    public {{../name}}({{this}} value)
+    {
+        _value = value!;
+        _type = typeof({{this}});
+    }
+
+{{/each}}
+
+    /// <summary>
+    /// Gets the underlying value.
+    /// </summary>
+    public object Value => _value;
+
+    /// <summary>
+    /// Attempts to get the value as the specified type.
+    /// </summary>
+    public bool TryGet<T>(out T? value)
+    {
+        if (_value is T v)
+        {
+            value = v;
+            return true;
+        }
+        value = default;
+        return false;
+    }
+}
+
+{{else}}
+/// <summary>
+{{#if description}}
+/// {{description}}
+{{else}}
+/// {{name}} schema type.
+{{/if}}
+/// </summary>
+public class {{name}}
+{
+{{#each properties}}
+    /// <summary>
+    {{#if description}}
+    /// {{description}}
+    {{/if}}
+    /// </summary>
+    [JsonPropertyName("{{name}}")]
+    {{#if (or nullable (not required))}}
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    {{/if}}
+    {{#if deprecated}}
+    [Obsolete]
+    {{/if}}
+    public {{#if (eq type "string")}}{{#if (eq format "date-time")}}DateTime{{else}}string{{/if}}{{else if (eq type "integer")}}int{{else if (eq type "number")}}double{{else if (eq type "boolean")}}bool{{else if (eq type "array")}}List<object>?{{else}}{{type}}{{/if}}{{#if (or nullable (not required))}}?{{/if}} {{pascalCase name}} { get; set; }
+{{/each}}
+}
+{{/if}}
+
+{{/if}}
+{{/each}}

package/templates/go/client.hbs

@@ -0,0 +1,158 @@
+package {{pkgName}}
+
+import (
+	"context"
+	"time"
+)
+
+// ── Client Configuration ──────────────────────────────────────────────────
+
+// ClientConfig holds all configuration for the API client.
+type ClientConfig struct {
+	BaseURL        string
+	Timeout        time.Duration
+	MaxRetries     int
+	DefaultHeaders map[string]string
+}
+
+// ClientOption is a functional option for configuring the client.
+type ClientOption func(*ClientConfig)
+
+// WithBaseURL sets the base URL for all API requests.
+func WithBaseURL(url string) ClientOption {
+	return func(c *ClientConfig) { c.BaseURL = url }
+}
+
+// WithTimeout sets the request timeout.
+func WithTimeout(d time.Duration) ClientOption {
+	return func(c *ClientConfig) { c.Timeout = d }
+}
+
+// WithMaxRetries sets the maximum number of retry attempts.
+func WithMaxRetries(n int) ClientOption {
+	return func(c *ClientConfig) { c.MaxRetries = n }
+}
+
+// WithDefaultHeader adds a default header sent with every request.
+func WithDefaultHeader(key, value string) ClientOption {
+	return func(c *ClientConfig) {
+		if c.DefaultHeaders == nil {
+			c.DefaultHeaders = make(map[string]string)
+		}
+		c.DefaultHeaders[key] = value
+	}
+}
+
+// DefaultConfig returns a ClientConfig populated with sensible defaults.
+func DefaultConfig() ClientConfig {
+	return ClientConfig{
+		BaseURL:    "{{baseUrl}}",
+		Timeout:    15 * time.Second,
+		MaxRetries: 3,
+	}
+}
+
+// ── Client ────────────────────────────────────────────────────────────────
+
+// Client is the primary API client for {{title}}.
+// It is safe for concurrent use by multiple goroutines.
+type Client struct {
+	config    ClientConfig
+	transport *Transport
+{{#each groups}}
+	{{pascalCase name}} *{{interfaceName}}
+{{/each}}
+}
+
+// NewClient creates a new {{title}} API client with the given options.
+//
+// Example:
+//
+//	client := petshop.NewClient(
+//	    petshop.WithBaseURL("https://api.example.com"),
+//	    petshop.WithTimeout(30*time.Second),
+//	)
+//	pets, err := client.Pets.List(ctx, nil)
+func NewClient(opts ...ClientOption) *Client {
+	cfg := DefaultConfig()
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+
+	t := NewTransport(TransportConfig{
+		BaseURL:    cfg.BaseURL,
+		Timeout:    cfg.Timeout,
+		MaxRetries: cfg.MaxRetries,
+		Headers:    cfg.DefaultHeaders,
+	})
+
+	return &Client{
+		config:    cfg,
+		transport: t,
+{{#each groups}}
+		{{pascalCase name}}: &{{interfaceName}}{transport: t},
+{{/each}}
+	}
+}
+
+// Transport returns the underlying HTTP transport for advanced use cases.
+func (c *Client) Transport() *Transport {
+	return c.transport
+}
+
+// ── Request / Response types ──────────────────────────────────────────────
+
+// RequestOptions holds per-request overrides.
+type RequestOptions struct {
+	// Timeout overrides the client-level timeout for this request.
+	Timeout time.Duration
+	// Headers are additional headers merged into the request.
+	Headers map[string]string
+}
+
+// ListParams is embedded by list operation parameter types to provide
+// common pagination and filtering fields.
+type ListParams struct {
+	Page  *int    `json:"page,omitempty"`
+	Limit *int    `json:"limit,omitempty"`
+}
+
+// Int returns a pointer to the given int value. Useful for optional
+// parameters in request structs.
+func Int(v int) *int { return &v }
+
+// String returns a pointer to the given string value.
+func String(v string) *string { return &v }
+
+// Bool returns a pointer to the given bool value.
+func Bool(v bool) *bool { return &v }
+
+{{#if hasSSE}}
+// ── SSE Types ─────────────────────────────────────────────────────────────
+
+// SSEEvent represents a parsed Server-Sent Event.
+type SSEEvent struct {
+	Event string
+	Data  string
+	ID    string
+	Retry int
+}
+
+// SSEOption configures an SSE stream subscription.
+type SSEOption func(*sseConfig)
+
+type sseConfig struct {
+	signal    context.Context
+	eventTypes []string
+}
+
+// WithSSESignal sets a context for cancellation of the SSE stream.
+func WithSSESignal(ctx context.Context) SSEOption {
+	return func(c *sseConfig) { c.signal = ctx }
+}
+
+// WithSSEEventTypes filters the stream to specific event types.
+func WithSSEEventTypes(types ...string) SSEOption {
+	return func(c *sseConfig) { c.eventTypes = types }
+}
+{{/if}}

package/templates/go/domain.hbs

@@ -0,0 +1,89 @@
+package {{pkgName}}
+
+import (
+{{#if hasSSE}}
+	"bufio"
+	"strings"
+{{/if}}
+	"context"
+)
+
+// {{interfaceName}} provides access to {{name}} API operations.
+type {{interfaceName}} struct {
+	transport *Transport
+}
+
+{{#each operations}}
+{{#if isEventStream}}
+func (api *{{../interfaceName}}) {{pascalCase name}}Stream(
+	ctx context.Context,
+{{#each pathParams}}
+	{{name}} string,
+{{/each}}
+{{#if queryType}}
+	params {{goQueryType queryType}},
+{{/if}}
+) (<-chan SSEEvent, <-chan error) {
+	eventCh := make(chan SSEEvent)
+	errCh := make(chan error, 1)
+	go func() {
+		defer close(eventCh)
+		defer close(errCh)
+		reqPath := buildPath("{{path}}"{{#each pathParams}}, "{{originalName}}", {{name}}{{/each}})
+		resp, err := api.transport.Stream(ctx, request{Method: "{{httpMethod}}", Path: reqPath})
+		if err != nil { errCh <- err; return }
+		defer resp.Body.Close()
+		scanner := bufio.NewScanner(resp.Body)
+		var current SSEEvent
+		for scanner.Scan() {
+			select {
+			case <-ctx.Done(): errCh <- ctx.Err(); return
+			default:
+			}
+			line := scanner.Text()
+			if line == "" {
+				if current.Data != "" { eventCh <- current; current = SSEEvent{} }
+				continue
+			}
+			if strings.HasPrefix(line, "event:") { current.Event = strings.TrimSpace(line[6:]) }
+			if strings.HasPrefix(line, "data:") { if current.Data != "" { current.Data += "\n" }; current.Data += strings.TrimSpace(line[5:]) }
+			if strings.HasPrefix(line, "id:") { current.ID = strings.TrimSpace(line[3:]) }
+		}
+	}()
+	return eventCh, errCh
+}
+
+{{else}}
+func (api *{{../interfaceName}}) {{pascalCase name}}(
+	ctx context.Context,
+{{#each pathParams}}
+	{{name}} string,
+{{/each}}
+{{#if requestBody}}
+	body *{{requestBody.type}},
+{{/if}}
+{{#if queryType}}
+	params {{goQueryType queryType}},
+{{/if}}
+) {{#if (eq responseType "void")}}error{{else}}(*{{responseType}}, error){{/if}} {
+	reqPath := buildPath("{{path}}"{{#each pathParams}}, "{{originalName}}", {{name}}{{/each}})
+	{{#if queryType}}q := buildQuery(params){{/if}}
+{{#if (eq responseType "void")}}
+	return api.transport.Execute(ctx, request{
+		Method: "{{httpMethod}}", Path: reqPath,
+{{#if queryType}}		Query: q,{{/if}}
+{{#if requestBody}}		Body: body,{{/if}}
+	}, nil)
+{{else}}
+	var result {{responseType}}
+	err := api.transport.Execute(ctx, request{
+		Method: "{{httpMethod}}", Path: reqPath,
+{{#if queryType}}		Query: q,{{/if}}
+{{#if requestBody}}		Body: body,{{/if}}
+	}, &result)
+	if err != nil { return nil, err }
+	return &result, nil
+{{/if}}
+}
+{{/if}}
+{{/each}}

package/templates/go/errors.hbs

@@ -0,0 +1,38 @@
+package {{pkgName}}
+
+import "fmt"
+
+// SDKError represents an error returned by the API.
+type SDKError struct {
+	// Status is the HTTP status code.
+	Status int
+	// Code is a machine-readable error code from the API.
+	Code string
+	// RequestID is the unique identifier for the request (for support).
+	RequestID string
+	// Message is a human-readable error description.
+	Message string
+}
+
+// Error implements the error interface.
+func (e *SDKError) Error() string {
+	if e.Code != "" {
+		return fmt.Sprintf("[%d] %s: %s", e.Status, e.Code, e.Message)
+	}
+	return fmt.Sprintf("[%d] %s", e.Status, e.Message)
+}
+
+// Unwrap returns nil since SDKError is the root cause.
+func (e *SDKError) Unwrap() error {
+	return nil
+}
+
+// NewSDKError creates a new SDKError.
+func NewSDKError(status int, code, message, requestID string) *SDKError {
+	return &SDKError{
+		Status:    status,
+		Code:      code,
+		Message:   message,
+		RequestID: requestID,
+	}
+}

package/templates/go/go-mod.hbs

@@ -0,0 +1,6 @@
+module {{packageName}}
+
+go 1.21
+
+require (
+)