@apollo-deploy/tesseract 0.9.1 → 1.0.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;
+        }
+    }
+}

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];
+        }
+    }
+}