@apollo-deploy/tesseract 0.9.1 → 1.2.0

package/templates/php/errors.hbs

@@ -0,0 +1,131 @@
+<?php
+
+/**
+ * @generated
+ * This file was automatically generated by Tesseract.
+ * DO NOT MODIFY THIS FILE DIRECTLY.
+ */
+
+declare(strict_types=1);
+
+namespace {{namespace}};
+
+use Throwable;
+
+/**
+ * Standard SDK error class.
+ *
+ * Wraps HTTP errors and transport failures with structured metadata
+ * including HTTP status, error code, and request ID for debugging.
+ */
+class SDKError extends \Exception
+{
+    /**
+     * HTTP status code (0 for non-HTTP / connection errors).
+     */
+    private int $httpStatus;
+
+    /**
+     * Machine-readable error code (e.g. "NOT_FOUND", "VALIDATION_ERROR").
+     */
+    private string $errorCode;
+
+    /**
+     * The x-request-id header value, if present in the response.
+     */
+    private ?string $requestId;
+
+    /**
+     * Raw response body for inspection.
+     *
+     * @var array<string, mixed>|null
+     */
+    private ?array $responseBody;
+
+    public function __construct(
+        string $message = 'An SDK error occurred',
+        int $status = 0,
+        string $code = 'SDK_ERROR',
+        ?string $requestId = null,
+        ?array $responseBody = null,
+        ?Throwable $previous = null,
+    ) {
+        parent::__construct($message, $status, $previous);
+
+        $this->httpStatus = $status;
+        $this->errorCode = $code;
+        $this->requestId = $requestId;
+        $this->responseBody = $responseBody;
+    }
+
+    /**
+     * Create an SDKError from a generic Throwable.
+     */
+    public static function fromException(Throwable $exception): self
+    {
+        return new self(
+            message: $exception->getMessage(),
+            status: $exception->getCode(),
+            code: 'TRANSPORT_ERROR',
+            previous: $exception,
+        );
+    }
+
+    /**
+     * Get the HTTP status code.
+     */
+    public function getHttpStatus(): int
+    {
+        return $this->httpStatus;
+    }
+
+    /**
+     * Get the machine-readable error code.
+     */
+    public function getErrorCode(): string
+    {
+        return $this->errorCode;
+    }
+
+    /**
+     * Get the request ID from the x-request-id header, if available.
+     */
+    public function getRequestId(): ?string
+    {
+        return $this->requestId;
+    }
+
+    /**
+     * Get the decoded response body, if available.
+     *
+     * @return array<string, mixed>|null
+     */
+    public function getResponseBody(): ?array
+    {
+        return $this->responseBody;
+    }
+
+    /**
+     * Check if this error is retryable (status >= 500 or 429).
+     */
+    public function isRetryable(): bool
+    {
+        return $this->httpStatus >= 500 || $this->httpStatus === 429;
+    }
+
+    /**
+     * Check if this is a client error (4xx).
+     */
+    public function isClientError(): bool
+    {
+        return $this->httpStatus >= 400 && $this->httpStatus < 500;
+    }
+
+    /**
+     * Check if this is a server error (5xx).
+     */
+    public function isServerError(): bool
+    {
+        return $this->httpStatus >= 500;
+    }
+}

package/templates/php/readme.hbs

@@ -0,0 +1,89 @@
+# {{title}} PHP SDK
+
+{{#if description}}
+{{description}}
+
+{{/if}}
+> This SDK was automatically generated by [Tesseract](https://www.npmjs.com/package/@apollo-deploy/tesseract).
+
+## Installation
+
+```bash
+composer require {{composerName}}
+```
+
+## Quick Start
+
+```php
+<?php
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+use {{namespace}}\Client;
+
+$client = new Client([
+    'baseUrl' => '{{baseUrl}}',
+{{#each securitySchemes}}
+    '{{configKey}}' => 'your-{{kebabCase name}}-credential',
+{{/each}}
+]);
+
+{{#with groups.[0]}}
+$api = $client->{{name}}();
+{{/with}}
+```
+
+## Configuration
+
+The `Client` constructor accepts an associative array with the following keys:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | `string` | `'{{baseUrl}}'` | Base URL for the API |
+{{#each securitySchemes}}
+| `{{configKey}}` | `string` | `null` | {{#if description}}{{description}}{{else}}{{type}} credential for {{name}}{{/if}} |
+{{/each}}
+| `timeoutMs` | `int` | `15000` | Request timeout in milliseconds |
+| `retries` | `array` | `['attempts' => 3, 'backoffMs' => 400, 'jitter' => true]` | Retry configuration |
+| `defaultHeaders` | `array` | `[]` | Default headers sent with every request |
+
+## API Reference
+
+{{#each groups}}
+### `{{className}}`
+
+{{#if description}}
+{{description}}
+
+{{/if}}
+| Method | HTTP | Path | Description |
+|--------|------|------|-------------|
+{{#each operations}}
+| `{{name}}()` | `{{upperCase httpMethod}}` | `{{path}}` | {{#if description}}{{description}}{{else}}-{{/if}} |
+{{/each}}
+
+{{/each}}
+
+## Types
+
+{{#each schemas}}
+{{#if isEnum}}
+- `{{name}}` — enum: {{#each enumValues}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
+{{else}}
+- `{{name}}`{{#if description}} — {{description}}{{/if}}
+{{/if}}
+{{/each}}
+
+## Error Handling
+
+```php
+<?php
+
+use {{namespace}}\SDKError;
+
+try {
+    $result = $client->{{groups.[0].name}}()->{{groups.[0].operations.[0].name}}(/* params */);
+} catch (SDKError $e) {
+    echo sprintf("Error %d: %s (%s)\n", $e->getHttpStatus(), $e->getMessage(), $e->getErrorCode());
+}
+```

package/templates/php/transport.hbs

@@ -0,0 +1,285 @@
+<?php
+
+/**
+ * @generated
+ * This file was automatically generated by Tesseract.
+ * DO NOT MODIFY THIS FILE DIRECTLY.
+ */
+
+declare(strict_types=1);
+
+namespace {{namespace}};
+
+use GuzzleHttp\Client as GuzzleClient;
+use GuzzleHttp\ClientInterface;
+use GuzzleHttp\Exception\ConnectException;
+use GuzzleHttp\Exception\RequestException;
+use GuzzleHttp\Psr7\Request;
+use GuzzleHttp\RequestOptions;
+use Psr\Http\Message\ResponseInterface;
+use Throwable;
+
+/**
+ * HTTP transport layer with retry logic and security scheme injection.
+ *
+ * Wraps a GuzzleHttp\Client and provides executeRequest() for typed
+ * request/response handling with automatic auth header injection
+ * and configurable retry with exponential backoff + jitter.
+ */
+class Transport
+{
+    private ClientInterface $http;
+
+    /** @var array<string, mixed> */
+    private array $config;
+
+    /**
+     * @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->config = $config;
+
+        $baseUrl = rtrim($config['baseUrl'] ?? '{{baseUrl}}', '/');
+        $timeoutMs = $config['timeoutMs'] ?? 15000;
+
+        $headers = $config['defaultHeaders'] ?? [];
+        $headers['Accept'] = $headers['Accept'] ?? 'application/json';
+        $headers['User-Agent'] = $headers['User-Agent'] ?? '{{clientName}}-php-sdk/{{version}}';
+
+        $this->http = new GuzzleClient([
+            'base_uri' => $baseUrl . '/',
+            'timeout' => $timeoutMs / 1000.0,
+            'http_errors' => false,
+            'headers' => $headers,
+        ]);
+    }
+
+    /**
+     * Execute an HTTP request with retry logic and auth injection.
+     *
+     * @param array{
+     *     method: string,
+     *     path: string,
+     *     query?: array<string, mixed>,
+     *     body?: mixed,
+     *     headers?: array<string, string>,
+     *     timeoutMs?: int,
+     * } $requestDef
+     * @return ResponseInterface
+     * @throws SDKError
+     */
+    public function executeRequest(array $requestDef): ResponseInterface
+    {
+        $method = strtoupper($requestDef['method']);
+        $path = ltrim($requestDef['path'], '/');
+        $query = $requestDef['query'] ?? [];
+        $body = $requestDef['body'] ?? null;
+        $extraHeaders = $requestDef['headers'] ?? [];
+        $timeoutMs = $requestDef['timeoutMs'] ?? null;
+
+        // ── Inject auth headers ────────────────────────────────────────────
+        $authHeaders = $this->buildAuthHeaders();
+
+        $options = [
+            RequestOptions::HEADERS => array_merge($authHeaders, $extraHeaders),
+        ];
+
+        if (!empty($query)) {
+            $options[RequestOptions::QUERY] = $query;
+        }
+
+        if ($body !== null) {
+            $options[RequestOptions::JSON] = $body;
+        }
+
+        if ($timeoutMs !== null) {
+            $options[RequestOptions::TIMEOUT] = $timeoutMs / 1000.0;
+        }
+
+        // ── Execute with retry ─────────────────────────────────────────────
+        return $this->executeWithRetry($method, $path, $options);
+    }
+
+    /**
+     * Execute with configurable retry logic.
+     */
+    private function executeWithRetry(string $method, string $path, array $options): ResponseInterface
+    {
+        $retryConfig = $this->config['retries'] ?? [];
+        $maxAttempts = $retryConfig['attempts'] ?? 3;
+        $baseBackoffMs = $retryConfig['backoffMs'] ?? 400;
+        $useJitter = $retryConfig['jitter'] ?? true;
+        $maxBackoffMs = $retryConfig['maxBackoffMs'] ?? 30000;
+
+        $lastException = null;
+
+        for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
+            try {
+                $request = new Request($method, $path, $options[RequestOptions::HEADERS] ?? []);
+                $response = $this->http->send($request, $options);
+
+                // Retry on server errors (5xx) and 429 (rate limit)
+                $status = $response->getStatusCode();
+                if ($status < 500 && $status !== 429) {
+                    return $response;
+                }
+
+                if ($attempt < $maxAttempts) {
+                    $delayMs = $this->calculateBackoff($attempt, $baseBackoffMs, $useJitter, $maxBackoffMs);
+                    $this->sleep($delayMs);
+                }
+            } catch (ConnectException $e) {
+                $lastException = $e;
+
+                if ($attempt < $maxAttempts) {
+                    $delayMs = $this->calculateBackoff($attempt, $baseBackoffMs, $useJitter, $maxBackoffMs);
+                    $this->sleep($delayMs);
+                }
+            } catch (RequestException $e) {
+                $response = $e->getResponse();
+                if ($response !== null) {
+                    $status = $response->getStatusCode();
+                    if ($status >= 500 || $status === 429) {
+                        $lastException = $e;
+                        if ($attempt < $maxAttempts) {
+                            $delayMs = $this->calculateBackoff($attempt, $baseBackoffMs, $useJitter, $maxBackoffMs);
+                            $this->sleep($delayMs);
+                        }
+                        continue;
+                    }
+                }
+                throw $this->mapToSDKError($e);
+            }
+        }
+
+        // All retries exhausted
+        if ($lastException instanceof RequestException) {
+            throw $this->mapToSDKError($lastException);
+        }
+
+        if ($lastException instanceof Throwable) {
+            throw SDKError::fromException($lastException);
+        }
+
+        throw new SDKError('Request failed after ' . $maxAttempts . ' attempts');
+    }
+
+    /**
+     * Build auth headers from configured security schemes.
+     *
+     * @return array<string, string>
+     */
+    private function buildAuthHeaders(): array
+    {
+        $headers = [];
+
+        {{#each securitySchemes}}
+        {{#if (eq type "apiKey")}}
+        {{#if (eq in "header")}}
+        // {{name}} — API key in header
+        if (!empty($this->config['{{configKey}}'])) {
+            $headers['{{paramName}}'] = $this->config['{{configKey}}'];
+        }
+        {{/if}}
+        {{/if}}
+
+        {{#if (and (eq type "http") (eq scheme "bearer"))}}
+        // {{name}} — Bearer token
+        if (!empty($this->config['{{configKey}}'])) {
+            $headers['Authorization'] = 'Bearer ' . $this->config['{{configKey}}'];
+        }
+        {{/if}}
+
+        {{#if (eq type "oauth2")}}
+        // {{name}} — OAuth2 access token
+        if (!empty($this->config['{{configKey}}'])) {
+            $headers['Authorization'] = 'Bearer ' . $this->config['{{configKey}}'];
+        }
+        {{/if}}
+
+        {{#if (eq type "openIdConnect")}}
+        // {{name}} — OpenID Connect token
+        if (!empty($this->config['{{configKey}}'])) {
+            $headers['Authorization'] = 'Bearer ' . $this->config['{{configKey}}'];
+        }
+        {{/if}}
+        {{/each}}
+
+        return $headers;
+    }
+
+    /**
+     * Calculate exponential backoff with optional jitter.
+     */
+    private function calculateBackoff(int $attempt, int $baseMs, bool $jitter, int $maxMs): int
+    {
+        $delay = $baseMs * (2 ** ($attempt - 1));
+
+        if ($jitter) {
+            $delay = (int) ($delay * (0.5 + (mt_rand() / mt_getrandmax()) * 0.5));
+        }
+
+        return min($delay, $maxMs);
+    }
+
+    /**
+     * Sleep for a given number of milliseconds.
+     */
+    private function sleep(int $milliseconds): void
+    {
+        usleep($milliseconds * 1000);
+    }
+
+    /**
+     * Map a Guzzle RequestException to an SDKError.
+     */
+    private function mapToSDKError(RequestException $exception): SDKError
+    {
+        $response = $exception->getResponse();
+
+        if ($response === null) {
+            return SDKError::fromException($exception);
+        }
+
+        $status = $response->getStatusCode();
+        $body = $this->decodeResponseBody($response);
+
+        $message = $body['message'] ?? $body['error'] ?? $exception->getMessage();
+        $code = $body['code'] ?? $body['error_code'] ?? 'UNKNOWN';
+        $requestId = $response->getHeaderLine('x-request-id') ?: null;
+
+        return new SDKError(
+            message: (string) $message,
+            status: $status,
+            code: (string) $code,
+            requestId: $requestId,
+            previous: $exception,
+        );
+    }
+
+    /**
+     * Decode a PSR-7 response body, returning an associative array.
+     *
+     * @return array<string, mixed>
+     */
+    private function decodeResponseBody(ResponseInterface $response): array
+    {
+        $contents = $response->getBody()->__toString();
+
+        try {
+            $decoded = json_decode($contents, true, 512, JSON_THROW_ON_ERROR);
+            return is_array($decoded) ? $decoded : ['raw' => $decoded];
+        } catch (Throwable) {
+            return ['raw' => $contents];
+        }
+    }
+}

package/templates/php/types.hbs

@@ -0,0 +1,95 @@
+<?php
+
+/**
+ * @generated
+ * This file was automatically generated by Tesseract.
+ * DO NOT MODIFY THIS FILE DIRECTLY.
+ */
+
+declare(strict_types=1);
+
+namespace {{namespace}};
+
+{{#each schemas}}
+{{#if isEnum}}
+/**
+{{#if description}}
+ * {{description}}
+ *
+{{/if}}
+ * @generated
+ */
+enum {{name}}: {{#each properties}}{{#if @first}}{{type}}{{/if}}{{/each}}
+{
+{{#each enumValues}}
+    case {{this}} = '{{this}}';
+{{/each}}
+}
+
+{{else if isTypeAlias}}
+{{!-- PHP type aliases are not direct; they are used as docblock hints --}}
+{{!-- Skipping type alias: {{name}} --}}
+
+{{else if isUnionType}}
+{{!-- PHP union types are handled via properties, not standalone declarations --}}
+{{!-- Skipping union type: {{name}} --}}
+
+{{else}}
+/**
+{{#if description}}
+ * {{description}}
+ *
+{{/if}}
+ * @generated
+ */
+class {{name}}{{#if extends}} extends {{extends}}{{/if}}
+{
+{{#each properties}}
+    /**
+     * @var {{tsType type nullable}}
+     */
+    public {{#if nullable}}?{{/if}}{{type}} ${{name}}{{#if defaultValue}} = {{{json defaultValue}}}{{/if}};
+
+{{/each}}
+
+    /**
+     * @param array<string, mixed> $data
+     */
+    public static function fromArray(array $data): self
+    {
+        $instance = new self();
+
+        {{#each properties}}
+        {{#if (eq type "string")}}
+        $instance->{{name}} = isset($data['{{name}}']) ? (string) $data['{{name}}'] : {{#if required}}throw new \InvalidArgumentException('Missing required field: {{name}}'){{else}}null{{/if}};
+        {{else if (eq type "int")}}
+        $instance->{{name}} = isset($data['{{name}}']) ? (int) $data['{{name}}'] : {{#if required}}throw new \InvalidArgumentException('Missing required field: {{name}}'){{else}}null{{/if}};
+        {{else if (eq type "float")}}
+        $instance->{{name}} = isset($data['{{name}}']) ? (float) $data['{{name}}'] : {{#if required}}throw new \InvalidArgumentException('Missing required field: {{name}}'){{else}}null{{/if}};
+        {{else if (eq type "bool")}}
+        $instance->{{name}} = isset($data['{{name}}']) ? (bool) $data['{{name}}'] : {{#if required}}throw new \InvalidArgumentException('Missing required field: {{name}}'){{else}}null{{/if}};
+        {{else if (eq type "array")}}
+        $instance->{{name}} = isset($data['{{name}}']) ? (array) $data['{{name}}'] : {{#if required}}[]{{else}}null{{/if}};
+        {{else}}
+        $instance->{{name}} = $data['{{name}}'] ?? {{#if required}}throw new \InvalidArgumentException('Missing required field: {{name}}'){{else}}null{{/if}};
+        {{/if}}
+
+        {{/each}}
+        return $instance;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        return [
+            {{#each properties}}
+            '{{name}}' => $this->{{name}},
+            {{/each}}
+        ];
+    }
+}
+
+{{/if}}
+{{/each}}

package/templates/python/client.hbs

@@ -0,0 +1,102 @@
+"""{{title}} SDK Client"""
+
+from typing import Optional, Dict, Any, List, Callable, Union
+import httpx
+from .transport import create_transport, SDKTransport, RequestOptions
+{{#each groups}}
+from .resources.{{fileName}} import {{interfaceName}}
+{{/each}}
+
+{{#if hasSSE}}
+# SSE support requires the sseclient-py package:
+#   pip install sseclient-py>=1.8.0
+{{/if}}
+
+class {{clientName}}ClientConfig:
+    """Configuration for {{title}} client."""
+
+    def __init__(
+        self,
+        base_url: str = "{{baseUrl}}",
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+        {{configKey}}: Optional[str] = None,
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
+        {{configKey}}: Optional[str] = None,
+{{/if}}
+{{#if (eq type "oauth2")}}
+        {{configKey}}: Optional[str] = None,
+{{/if}}
+{{#if (eq type "openIdConnect")}}
+        {{configKey}}: Optional[str] = None,
+{{/if}}
+{{/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
+{{#each securitySchemes}}
+        self.{{configKey}} = {{configKey}}
+{{/each}}
+        self.timeout_ms = timeout_ms
+        self.retries = retries
+        self.default_headers = default_headers or {}
+        self.on_request = on_request
+        self.on_response = on_response
+        self.on_error = on_error
+
+
+class {{clientName}}Client:
+    """{{title}} SDK Client"""
+
+    def __init__(self, config: Optional[{{clientName}}ClientConfig] = None):
+        self.config = config or {{clientName}}ClientConfig()
+        self._transport = create_transport(
+            base_url=self.config.base_url,
+{{#each securitySchemes}}
+            {{configKey}}=self.config.{{configKey}},
+{{/each}}
+            timeout_ms=self.config.timeout_ms,
+            retries=self.config.retries,
+            default_headers=self.config.default_headers,
+            on_request=self.config.on_request,
+            on_response=self.config.on_response,
+            on_error=self.config.on_error,
+        )
+{{#each groups}}
+        self.{{snakeCase name}} = {{interfaceName}}(self._transport)
+{{/each}}
+
+
+def create_{{snakeCase clientName}}_client(
+    base_url: str = "{{baseUrl}}",
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+    {{configKey}}: Optional[str] = None,
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
+    {{configKey}}: Optional[str] = None,
+{{/if}}
+{{#if (eq type "oauth2")}}
+    {{configKey}}: Optional[str] = None,
+{{/if}}
+{{#if (eq type "openIdConnect")}}
+    {{configKey}}: Optional[str] = None,
+{{/if}}
+{{/each}}
+    **kwargs,
+) -> {{clientName}}Client:
+    """Create a new {{title}} SDK client."""
+    config = {{clientName}}ClientConfig(
+        base_url=base_url,
+{{#each securitySchemes}}
+        {{configKey}}={{configKey}},
+{{/each}}
+        **kwargs,
+    )
+    return {{clientName}}Client(config)