@apollo-deploy/tesseract 0.9.1 → 1.2.0

package/templates/python/domain.hbs

@@ -0,0 +1,139 @@
+"""{{interfaceName}} operations."""
+
+from typing import Optional, Dict, Any, List
+{{#if imports.length}}
+from ..types import {{#each imports}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}
+{{/if}}
+from ..transport import SDKTransport, RequestOptions
+from ..errors import SDKError
+
+
+class {{interfaceName}}:
+    """{{#if description}}{{description}}{{else}}{{interfaceName}} API operations{{/if}}"""
+
+    def __init__(self, transport: SDKTransport):
+        self._transport = transport
+
+{{#each operations}}
+{{#if isEventStream}}
+    def {{snakeCase name}}(
+        self,
+{{#each pathParams}}
+        {{name}}: str,
+{{/each}}
+{{#if (and queryType (not queryParams.length))}}
+        *,
+        query: Optional[Dict[str, Any]] = None,
+{{/if}}
+{{#if queryParams.length}}
+        *,
+{{#each queryParams}}
+        {{name}}: Optional[{{pythonType type}}] = None,
+{{/each}}
+{{/if}}
+        options: Optional[RequestOptions] = None,
+    ):
+        """{{#if summary}}{{summary}}{{#if description}} - {{description}}{{/if}}{{else if description}}{{description}}{{/if}} (SSE stream)
+        """
+{{#if deprecated}}
+        # @deprecated {{deprecationMessage}}
+{{/if}}
+        # Build path with parameter substitution
+        _path = "{{path}}"
+{{#each pathParams}}
+        _path = _path.replace("{" + "{{originalName}}" + "}", str({{name}}))
+{{/each}}
+
+        # Build query parameters
+        _query: Dict[str, Any] = {}
+{{#each queryParams}}
+        if query is not None and hasattr(query, "{{name}}") and getattr(query, "{{name}}") is not None:
+            _query["{{originalName}}"] = getattr(query, "{{name}}")
+{{/each}}
+
+        response = self._transport.request(
+            method="{{httpMethod}}",
+            path=_path,
+            query=_query if _query else None,
+            options=options,
+        )
+        return response.json()
+
+{{else}}
+    def {{snakeCase name}}(
+        self,
+{{#each pathParams}}
+        {{name}}: str,
+{{/each}}
+{{#if requestBody}}
+        body: {{pythonType requestBody.type}},
+{{/if}}
+{{#if (and queryType (not queryParams.length))}}
+        *,
+        query: Optional[Dict[str, Any]] = None,
+{{/if}}
+{{#if queryParams.length}}
+        *,
+{{#each queryParams}}
+        {{name}}: Optional[{{pythonType type}}] = None,
+{{/each}}
+{{/if}}
+{{#if headerType}}
+        headers: Optional[{{pythonType headerType}}] = None,
+{{/if}}
+        options: Optional[RequestOptions] = None,
+    ) -> {{pythonType responseType}}:
+        """{{#if summary}}{{summary}}{{#if description}} - {{description}}{{/if}}{{else if description}}{{description}}{{/if}}
+        """
+{{#if deprecated}}
+        # @deprecated {{deprecationMessage}}
+{{/if}}
+        # Build path with parameter substitution
+        _path = "{{path}}"
+{{#each pathParams}}
+        _path = _path.replace("{" + "{{originalName}}" + "}", str({{name}}))
+{{/each}}
+
+        # Build query parameters
+        _query: Dict[str, Any] = {}
+{{#each queryParams}}
+        if {{name}} is not None:
+            _query["{{originalName}}"] = {{name}}
+{{/each}}
+{{#if queryType}}
+        if query is not None:
+            _items = query.__dict__.items() if hasattr(query, "__dict__") else []
+            for k, v in _items:
+                if v is not None:
+                    _query[k] = v
+{{/if}}
+
+        # Build headers
+        _headers: Dict[str, str] = {}
+{{#each headerParams}}
+        if headers is not None and hasattr(headers, "{{name}}") and getattr(headers, "{{name}}") is not None:
+            _headers["{{originalName}}"] = str(getattr(headers, "{{name}}"))
+{{/each}}
+
+{{#if (hasRequestBody this)}}
+        _content_type = "{{requestBody.contentType}}"
+{{/if}}
+
+        response = self._transport.request(
+            method="{{httpMethod}}",
+            path=_path,
+{{#if (or queryParams.length queryType)}}
+            query=_query if _query else None,
+{{/if}}
+{{#if (hasRequestBody this)}}
+            body=body,
+            content_type=_content_type,
+{{/if}}
+{{#if (or headerParams.length (hasRequestBody this))}}
+            options=RequestOptions(headers=_headers if _headers else None),
+{{/if}}
+        )
+        return response.json()
+
+{{/if}}
+{{/each}}

package/templates/python/index.hbs

@@ -0,0 +1,20 @@
+"""
+{{title}} Python SDK
+"""
+
+from .client import create_{{snakeCase clientName}}_client, {{clientName}}Client
+from .errors import SDKError
+from .resources import (
+{{#each groups}}
+    {{interfaceName}},
+{{/each}}
+)
+
+__all__ = [
+    "create_{{snakeCase clientName}}_client",
+    "{{clientName}}Client",
+    "SDKError",
+{{#each groups}}
+    "{{interfaceName}}",
+{{/each}}
+]

package/templates/python/pyproject.hbs

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "{{packageName}}"
+version = "{{#if packageVersion}}{{packageVersion}}{{else}}{{version}}{{/if}}"
+description = "{{#if description}}{{description}}{{else}}Python SDK for {{title}}{{/if}}"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+    "python-dateutil>=2.8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24.0",
+    "mypy>=1.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["{{moduleName}}*"]

package/templates/python/readme.hbs

@@ -0,0 +1,64 @@
+# {{title}} Python SDK
+
+{{#if description}}
+{{description}}
+{{/if}}
+
+> Auto-generated by Tesseract.
+
+## Installation
+
+```bash
+pip install {{packageName}}
+```
+
+## Quick Start
+
+```python
+from {{moduleName}} import create_{{snakeCase clientName}}_client
+
+client = create_{{snakeCase clientName}}_client(
+    base_url="{{baseUrl}}",
+{{#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}}
+)
+
+{{#with groups.[0]}}
+# Example: {{interfaceName}}
+result = client.{{snakeCase name}}.{{snakeCase operations.[0].name}}()
+{{/with}}
+```
+
+## API Reference
+
+{{#each groups}}
+### {{interfaceName}}
+
+{{#if description}}
+{{description}}
+{{/if}}
+
+| Method | HTTP | Path | Description |
+|--------|------|------|-------------|
+{{#each operations}}
+| `{{name}}` | {{httpMethod}} | `{{path}}` | {{#if description}}{{description}}{{else}}-{{/if}} |
+{{/each}}
+
+{{/each}}
+
+## Error Handling
+
+```python
+from {{moduleName}}.errors import SDKError
+
+try:
+    result = client.some_api.some_method()
+except SDKError as e:
+    print(f"Error {e.status}: {e.message} ({e.code})")
+```

package/templates/python/resources-init.hbs

@@ -0,0 +1,11 @@
+"""API resource modules for {{moduleName}}."""
+
+{{#each groups}}
+from .{{fileName}} import {{interfaceName}}
+{{/each}}
+
+__all__ = [
+{{#each groups}}
+    "{{interfaceName}}",
+{{/each}}
+]

package/templates/python/transport.hbs

@@ -0,0 +1,191 @@
+"""HTTP transport layer for {{moduleName}}."""
+
+import time
+import json
+import random
+from typing import Optional, Dict, Any, Callable
+from urllib.parse import urlencode
+import httpx
+from .errors import SDKError
+
+
+class RequestOptions:
+    """Per-request options."""
+
+    def __init__(
+        self,
+        timeout_ms: Optional[int] = None,
+        headers: Optional[Dict[str, str]] = None,
+        signal: Optional[Any] = None,
+    ):
+        self.timeout_ms = timeout_ms
+        self.headers = headers or {}
+        self.signal = signal
+
+
+class SDKTransport:
+    """HTTP transport with retry, auth, and error handling."""
+
+    def __init__(
+        self,
+        base_url: str,
+{{#each securitySchemes}}
+        {{configKey}}: Optional[str] = None,
+{{/each}}
+        timeout_ms: int = 15000,
+        retries: int = 3,
+        default_headers: Optional[Dict[str, str]] = None,
+        on_request: Optional[Callable] = None,
+        on_response: Optional[Callable] = None,
+        on_error: Optional[Callable] = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+{{#each securitySchemes}}
+        self._{{configKey}} = {{configKey}}
+{{/each}}
+        self.timeout_ms = timeout_ms
+        self.max_retries = retries
+        self.default_headers = default_headers or {}
+        self.on_request = on_request
+        self.on_response = on_response
+        self.on_error = on_error
+        self._client = httpx.Client(timeout=timeout_ms / 1000.0)
+
+    def _build_headers(self, extra_headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        headers = {**self.default_headers}
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+        if self._{{configKey}}:
+            headers["{{paramName}}"] = self._{{configKey}}
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
+        if self._{{configKey}}:
+            headers["Authorization"] = "Bearer " + self._{{configKey}}
+{{/if}}
+{{#if (eq type "oauth2")}}
+        if self._{{configKey}}:
+            headers["Authorization"] = "Bearer " + self._{{configKey}}
+{{/if}}
+{{#if (eq type "openIdConnect")}}
+        if self._{{configKey}}:
+            headers["Authorization"] = "Bearer " + self._{{configKey}}
+{{/if}}
+{{/each}}
+        if extra_headers:
+            headers.update(extra_headers)
+        return headers
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[Any] = None,
+        content_type: str = "application/json",
+        options: Optional[RequestOptions] = None,
+    ) -> httpx.Response:
+        """Execute an HTTP request with retry logic."""
+        url = self.base_url + path
+        headers = self._build_headers(options.headers if options else None)
+        timeout = (options.timeout_ms if options and options.timeout_ms else self.timeout_ms) / 1000.0
+
+        if query:
+            filtered = {k: v for k, v in query.items() if v is not None}
+            if filtered:
+                url += "?" + urlencode(filtered)
+
+        data = None
+        if body is not None:
+            if content_type == "application/json":
+                data = json.dumps(body, default=str)
+                headers["Content-Type"] = "application/json"
+            else:
+                data = body
+
+        last_error = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                if self.on_request:
+                    self.on_request(method, url, attempt)
+
+                response = self._client.request(
+                    method=method,
+                    url=url,
+                    headers=headers,
+                    content=data,
+                    timeout=timeout,
+                )
+
+                if self.on_response:
+                    self.on_response(response)
+
+                if response.status_code >= 400:
+                    self._handle_error_response(response)
+
+                return response
+
+            except httpx.TimeoutException as e:
+                last_error = SDKError("Request timed out: " + str(e), 0, "timeout")
+            except httpx.NetworkError as e:
+                last_error = SDKError("Network error: " + str(e), 0, "network_error")
+            except SDKError:
+                raise
+            except Exception as e:
+                last_error = SDKError("Request failed: " + str(e), 0, "unknown_error")
+
+            if attempt < self.max_retries:
+                delay = min(1000 * (2 ** attempt) + random.uniform(0, 500), 30000) / 1000.0
+                time.sleep(delay)
+
+        if self.on_error and last_error:
+            self.on_error(last_error)
+        raise last_error
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        try:
+            body = response.json()
+            error_code = body.get("error", "unknown_error")
+            message = body.get("message", response.text)
+            request_id = body.get("request_id")
+            raise SDKError(message, response.status_code, error_code, request_id)
+        except (json.JSONDecodeError, KeyError):
+            raise SDKError(
+                "HTTP " + str(response.status_code) + ": " + str(response.text)[:200],
+                response.status_code,
+                "http_error",
+            )
+
+    def close(self):
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+def create_transport(
+    base_url: str,
+{{#each securitySchemes}}
+    {{configKey}}: Optional[str] = None,
+{{/each}}
+    timeout_ms: int = 15000,
+    retries: int = 3,
+    default_headers: Optional[Dict[str, str]] = None,
+    on_request: Optional[Callable] = None,
+    on_response: Optional[Callable] = None,
+    on_error: Optional[Callable] = None,
+) -> SDKTransport:
+    return SDKTransport(
+        base_url=base_url,
+{{#each securitySchemes}}
+        {{configKey}}={{configKey}},
+{{/each}}
+        timeout_ms=timeout_ms,
+        retries=retries,
+        default_headers=default_headers,
+        on_request=on_request,
+        on_response=on_response,
+        on_error=on_error,
+    )

package/templates/python/types-errors.hbs

@@ -0,0 +1,75 @@
+"""Error classes for {{moduleName}}."""
+
+from typing import Optional, Dict, Any
+
+
+class SDKError(Exception):
+    """Structured error thrown by all SDK operations."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        code: str,
+        request_id: Optional[str] = None,
+        timestamp: Optional[str] = None,
+        path: Optional[str] = None,
+        method: Optional[str] = None,
+        hint: Optional[str] = None,
+        details: Optional[Any] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.timestamp = timestamp
+        self.path = path
+        self.method = method
+        self.hint = hint
+        self.details = details
+
+    def is_rate_limited(self) -> bool:
+        return self.code == "rate_limit_exceeded"
+
+    def is_auth_error(self) -> bool:
+        return self.code in ("unauthorized", "credential_expired", "credential_revoked")
+
+    def is_forbidden(self) -> bool:
+        return self.code == "forbidden"
+
+    def is_not_found(self) -> bool:
+        return self.code == "not_found"
+
+    def is_validation_error(self) -> bool:
+        return self.code in (
+            "validation_failed",
+            "request_validation_failed",
+            "bad_request",
+            "unprocessable_entity",
+        )
+
+    def is_server_error(self) -> bool:
+        return self.status >= 500
+
+    def is_client_error(self) -> bool:
+        return 400 <= self.status < 500
+
+    def is_retryable(self) -> bool:
+        return (
+            self.code in ("network_error", "gateway_timeout")
+            or self.status == 429
+            or self.status >= 500
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "message": self.message,
+            "status": self.status,
+            "code": self.code,
+            "request_id": self.request_id,
+            "timestamp": self.timestamp,
+            "path": self.path,
+            "method": self.method,
+            "hint": self.hint,
+        }

package/templates/python/types.hbs

@@ -0,0 +1,79 @@
+"""Generated type definitions for {{moduleName}}."""
+
+from typing import Optional, List, Dict, Any, Literal, Union
+from datetime import datetime
+from pydantic import BaseModel, Field
+
+
+# -- Pagination --------------------------------------------------
+
+class PaginationQuery(BaseModel):
+    page: Optional[int] = Field(None, description="Page number (1-indexed)")
+    limit: Optional[int] = Field(None, description="Number of items per page")
+    sort_by: Optional[str] = Field(None, description="Column name to sort by")
+    sort_order: Optional[Literal["asc", "desc"]] = Field(None, description="Sort direction")
+
+
+class PageMeta(BaseModel):
+    size: int
+    total_pages: int
+    has_more: bool
+
+
+class Page(BaseModel):
+    data: List[Any]
+    page: PageMeta
+
+
+# -- Common Responses --------------------------------------------
+
+class SuccessResponse(BaseModel):
+    success: bool
+    message: Optional[str] = None
+
+
+class MessageResponse(BaseModel):
+    message: str
+
+
+class ApiErrorEnvelope(BaseModel):
+    error: str
+    message: str
+    status: int
+    request_id: Optional[str] = None
+    timestamp: Optional[str] = None
+    path: Optional[str] = None
+    method: Optional[str] = None
+    hint: Optional[str] = None
+
+
+# -- Generated Schemas -------------------------------------------
+
+{{#each schemas}}
+{{#if (eq ownership.kind "external")}}
+{{else}}
+{{#if isEnum}}
+class {{name}}(str):
+    """{{#if description}}{{description}}{{else}}Enum for {{name}}{{/if}}"""
+{{#each enumValues}}
+    {{pascalCase this}} = "{{this}}"
+{{/each}}
+
+{{else if isUnionType}}
+{{name}} = Union[{{#each unionMembers}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}]
+"""{{#if description}}{{description}}{{else}}Union type for {{name}}{{/if}}"""
+
+{{else if isTypeAlias}}
+{{name}} = {{additionalPropertiesType}}
+"""{{#if description}}{{description}}{{else}}Type alias for {{name}}{{/if}}"""
+
+{{else}}
+class {{name}}(BaseModel):
+    """{{#if description}}{{description}}{{else}}Schema for {{name}}{{/if}}"""
+{{#each properties}}
+    {{name}}: {{#if nullable}}Optional[{{/if}}{{pythonType type}}{{#if nullable}}] = None{{else}}{{#unless required}} = None{{/unless}}{{/if}}
+{{/each}}
+
+{{/if}}
+{{/if}}
+{{/each}}

package/templates/ruby/Gemfile.hbs

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

package/templates/ruby/client.hbs

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "transport"
+{{#each groups}}
+require_relative "resources/{{fileName}}"
+{{/each}}
+
+module {{pascalCase meta.clientName}}
+  # Configuration for the {{meta.title}} SDK client.
+  class Config
+    # @return [String] the base URL for API requests
+    attr_accessor :base_url
+    # @return [Integer] request timeout in seconds
+    attr_accessor :timeout
+    # @return [Hash] retry configuration
+    attr_accessor :retries
+    # @return [Hash] default headers sent with every request
+    attr_accessor :default_headers
+    {{#each securitySchemes}}
+    # @return [String, nil] credential for {{name}} security scheme
+    attr_accessor :{{camelCase name}}
+    {{/each}}
+
+    # @param base_url [String] the base URL for API requests
+    # @param timeout [Integer] request timeout in seconds (default: 15)
+    # @param retries [Hash] retry configuration
+    # @param default_headers [Hash] headers sent with every request
+    {{#each securitySchemes}}
+    # @param {{camelCase name}} [String, nil] credential for {{name}}
+    {{/each}}
+    def initialize(
+      base_url: '{{meta.baseUrl}}',
+      timeout: 15,
+      retries: { attempts: 3, backoff: 0.4, jitter: true, max_backoff: 30.0 },
+      default_headers: {},
+      {{#each securitySchemes}}
+      {{camelCase name}}: nil,
+      {{/each}}
+      **_
+    )
+      @base_url = base_url
+      @timeout = timeout
+      @retries = retries
+      @default_headers = default_headers
+      {{#each securitySchemes}}
+      @{{camelCase name}} = {{camelCase name}}
+      {{/each}}
+    end
+  end
+
+  # Main client for the {{meta.title}} API.
+  #
+  # Provides access to all API domains as instance methods.
+  class Client
+    {{#each groups}}
+    # @return [{{pascalCase ../meta.clientName}}::{{pascalCase name}}]
+    attr_reader :{{name}}
+    {{/each}}
+
+    # @return [{{pascalCase meta.clientName}}::Config] the client configuration
+    attr_reader :config
+
+    # @return [{{pascalCase meta.clientName}}::Transport] the underlying HTTP transport
+    attr_reader :transport
+
+    # Create a new API client.
+    #
+    # @param config [{{pascalCase meta.clientName}}::Config, Hash, nil]
+    #   Either a Config instance or keyword arguments matching Config#initialize.
+    def initialize(config = nil)
+      @config = if config.is_a?(Config)
+                  config
+                elsif config.is_a?(Hash)
+                  Config.new(**config)
+                else
+                  Config.new
+                end
+
+      @transport = Transport.new(@config)
+
+      {{#each groups}}
+      @{{name}} = {{pascalCase ../meta.clientName}}::{{pascalCase name}}.new(@transport)
+      {{/each}}
+    end
+  end
+end