@apollo-deploy/tesseract 0.9.1 → 1.0.0

package/templates/rust/error.hbs

@@ -0,0 +1,74 @@
+use thiserror::Error;
+
+/// Primary error type for the {{crateName}} SDK.
+///
+/// All API methods return `Result<T, SdkError>`.
+#[derive(Error, Debug)]
+pub enum SdkError {
+    /// The API returned an error response (4xx/5xx).
+    #[error("API error (status {status}): {message}")]
+    ApiError {
+        /// HTTP status code.
+        status: u16,
+        /// Machine-readable error code (if available).
+        code: Option<String>,
+        /// Human-readable error message.
+        message: String,
+        /// Raw response body for debugging.
+        body: String,
+    },
+
+    /// A network-level error occurred (DNS, TLS, connection refused, timeout).
+    #[error("network error: {0}")]
+    NetworkError(String),
+
+    /// Failed to deserialize the response body.
+    #[error("deserialization error: {0}")]
+    DeserializationError(String),
+
+    /// The request parameters failed client-side validation.
+    #[error("validation error: {0}")]
+    ValidationError(String),
+}
+
+impl SdkError {
+    /// Returns the HTTP status code, if this is an `ApiError`.
+    pub fn status(&self) -> Option<u16> {
+        match self {
+            Self::ApiError { status, .. } => Some(*status),
+            _ => None,
+        }
+    }
+
+    /// Returns `true` if this error was caused by the server (5xx).
+    pub fn is_server_error(&self) -> bool {
+        matches!(self, Self::ApiError { status, .. } if *status >= 500)
+    }
+
+    /// Returns `true` if this error was caused by the client (4xx).
+    pub fn is_client_error(&self) -> bool {
+        matches!(self, Self::ApiError { status, .. } if *status >= 400 && *status < 500)
+    }
+
+    /// Returns `true` if this is a network error (should be retried safely).
+    pub fn is_retryable(&self) -> bool {
+        matches!(
+            self,
+            Self::NetworkError(_)
+                | Self::ApiError {
+                    status: 429 | 502 | 503 | 504,
+                    ..
+                }
+        )
+    }
+
+    /// Returns the error message as a string.
+    pub fn message(&self) -> &str {
+        match self {
+            Self::ApiError { message, .. } => message.as_str(),
+            Self::NetworkError(msg) => msg.as_str(),
+            Self::DeserializationError(msg) => msg.as_str(),
+            Self::ValidationError(msg) => msg.as_str(),
+        }
+    }
+}

package/templates/rust/lib.hbs

@@ -0,0 +1,85 @@
+//! {{title}}
+//!
+//! {{#if description}}{{description}}{{else}}Auto-generated Rust SDK for the {{title}} API.{{/if}}
+//!
+//! # Quick Start
+//!
+//! Add to your `Cargo.toml`:
+//!
+//! ```toml
+//! [dependencies]
+//! {{crateName}} = "{{#if packageVersion}}{{packageVersion}}{{else}}0.1.0{{/if}}"
+//! ```
+//!
+//! Then use it:
+//!
+//! ```rust,no_run
+//! use {{crateName}}::Client;
+//! use {{crateName}}::ClientConfig;
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     let mut config = ClientConfig::default();
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+//!     config.{{snakeCase configKey}} = Some("your-api-key".to_string());
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
+//!     config.{{snakeCase configKey}} = Some("your-bearer-token".to_string());
+{{/if}}
+{{/each}}
+//!
+//!     let client = Client::new(config);
+//!
+//!     // Use domain clients
+//!     // let result = client.{{#each groups}}{{#if @first}}{{snakeCase name}}{{/if}}{{/each}}.some_method().await?;
+//!
+//!     Ok(())
+//! }
+//! ```
+//!
+//! ## API Reference
+//!
+{{#each groups}}
+//! ### `{{interfaceName}}`
+//! {{#if description}}{{description}}{{/if}}
+//!
+{{#each operations}}
+//! - `{{snakeCase name}}()` — {{#if summary}}{{summary}}{{else}}No summary{{/if}}
+{{/each}}
+//!
+{{/each}}
+//!
+//! ## Error Handling
+//!
+//! All API methods return `Result<T, SdkError>`. The `SdkError` enum covers:
+//!
+//! - **ApiError** — server returned an error response (4xx/5xx)
+//! - **NetworkError** — request failed due to network issues
+//! - **DeserializationError** — response body could not be parsed
+//! - **ValidationError** — invalid request parameters
+//!
+//! ```rust
+//! match client.some_domain.some_method().await {
+//!     Ok(response) => println!("Success: {:?}", response),
+//!     Err(SdkError::ApiError { status, .. }) => eprintln!("API error ({}): {}", status, error),
+//!     Err(SdkError::NetworkError(e)) => eprintln!("Network error: {}", e),
+//!     Err(e) => eprintln!("Other error: {}", e),
+//! }
+//! ```
+
+pub mod client;
+pub mod transport;
+pub mod error;
+pub mod types;
+pub mod api;
+
+pub use client::*;
+pub use error::SdkError;
+
+/// Re-export API resource modules
+pub mod resources {
+{{#each groups}}
+    pub use super::api::{{snakeCase fileName}}::*;
+{{/each}}
+}

package/templates/rust/readme.hbs

@@ -0,0 +1,77 @@
+# {{title}}
+
+{{#if description}}{{description}}{{/if}}
+
+{{#unless description}}An auto-generated Rust SDK for the {{title}} API.{{/unless}}
+
+## Installation
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+{{crateName}} = "{{#if packageVersion}}{{packageVersion}}{{else}}0.1.0{{/if}}"
+```
+
+## Quick Start
+
+```rust
+use {{crateName}}::Client;
+use {{crateName}}::ClientConfig;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut config = ClientConfig::default();
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+    config.{{snakeCase configKey}} = Some("your-api-key".to_string());
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
+    config.{{snakeCase configKey}} = Some("your-bearer-token".to_string());
+{{/if}}
+{{/each}}
+
+    let client = Client::new(config);
+
+    // Use domain clients
+{{#each groups}}
+{{#if @first}}
+    // let result = client.{{snakeCase name}}.some_operation().await?;
+{{/if}}
+{{/each}}
+
+    Ok(())
+}
+```
+
+## API Reference
+
+{{#each groups}}
+### {{interfaceName}}
+
+{{#if description}}
+{{description}}
+{{/if}}
+
+| Method | HTTP | Description |
+|--------|------|-------------|
+{{#each operations}}
+| `{{snakeCase name}}()` | `{{httpMethod}}` | {{#if summary}}{{summary}}{{else}}—{{/if}} |
+{{/each}}
+
+{{/each}}
+
+## Error Handling
+
+All API methods return `Result<T, SdkError>`. The `SdkError` enum has these variants:
+
+| Variant | Description |
+|---------|-------------|
+| `ApiError` | Server returned an error (4xx/5xx) |
+| `NetworkError` | Request failed due to connectivity issues |
+| `DeserializationError` | Response body could not be parsed |
+| `ValidationError` | Invalid request parameters |
+
+## License
+
+MIT

package/templates/rust/transport.hbs

@@ -0,0 +1,287 @@
+use crate::error::SdkError;
+use reqwest::{Client as ReqwestClient, Method, RequestBuilder, Response, StatusCode};
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+use std::sync::Arc;
+use std::time::Duration;
+use url::Url;
+
+/// Internal transport configuration.
+#[derive(Debug, Clone)]
+pub struct TransportConfig {
+    pub base_url: String,
+{{#each securitySchemes}}
+    pub {{snakeCase configKey}}: Option<String>,
+{{/each}}
+    pub timeout: Duration,
+    pub max_retries: u32,
+}
+
+/// HTTP transport layer for the SDK.
+///
+/// Handles request building, authentication, retries, and error mapping.
+/// Cloning a `Transport` produces a shallow clone that shares the underlying
+/// reqwest client.
+#[derive(Clone)]
+pub struct Transport {
+    client: ReqwestClient,
+    config: Arc<TransportConfig>,
+}
+
+impl Transport {
+    /// Create a new transport with the given configuration.
+    pub fn new(config: TransportConfig) -> Self {
+        let client = ReqwestClient::builder()
+            .timeout(config.timeout)
+            .build()
+            .expect("failed to build reqwest client");
+
+        Self {
+            client,
+            config: Arc::new(config),
+        }
+    }
+
+    /// Execute a request, deserializing the response body as JSON.
+    pub async fn execute<T: DeserializeOwned>(
+        &self,
+        method: Method,
+        path: &str,
+        query: Option<&[(String, String)]>,
+        body: Option<&(impl Serialize + ?Sized)>,
+        headers: Option<&[(String, String)]>,
+    ) -> Result<T, SdkError> {
+        let url = self.build_url(path, query)?;
+
+        let mut req = self.client.request(method, url);
+
+        req = self.apply_auth(req);
+        req = self.apply_headers(req, headers);
+
+        if let Some(b) = body {
+            req = req.json(b);
+        }
+
+        let response = self.execute_with_retry(req).await?;
+
+        self.handle_response(response).await
+    }
+
+    /// Execute a request that returns the raw response text.
+    pub async fn execute_raw(
+        &self,
+        method: Method,
+        path: &str,
+        query: Option<&[(String, String)]>,
+        body: Option<&(impl Serialize + ?Sized)>,
+        headers: Option<&[(String, String)]>,
+    ) -> Result<String, SdkError> {
+        let url = self.build_url(path, query)?;
+
+        let mut req = self.client.request(method, url);
+
+        req = self.apply_auth(req);
+        req = self.apply_headers(req, headers);
+
+        if let Some(b) = body {
+            req = req.json(b);
+        }
+
+        let response = self.execute_with_retry(req).await?;
+
+        let status = response.status();
+        let text = response.text().await.map_err(|e| {
+            SdkError::DeserializationError(format!("failed to read response body: {}", e))
+        })?;
+
+        if status.is_success() {
+            Ok(text)
+        } else {
+            Err(self.build_api_error(status, &text))
+        }
+    }
+
+    // ── private helpers ─────────────────────────────────────────────────────
+
+    fn build_url(
+        &self,
+        path: &str,
+        query: Option<&[(String, String)]>,
+    ) -> Result<Url, SdkError> {
+        let base = Url::parse(&self.config.base_url).map_err(|e| {
+            SdkError::ValidationError(format!("invalid base URL: {}", e))
+        })?;
+
+        let joined = base.join(path).map_err(|e| {
+            SdkError::ValidationError(format!("invalid path '{}': {}", path, e))
+        })?;
+
+        if let Some(params) = query {
+            let mut url = joined;
+            {
+                let mut qp = url.query_pairs_mut();
+                for (k, v) in params {
+                    qp.append_pair(k, v);
+                }
+            }
+            Ok(url)
+        } else {
+            Ok(joined)
+        }
+    }
+
+    fn apply_auth(&self, mut req: RequestBuilder) -> RequestBuilder {
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+{{#if (eq in "header")}}
+        if let Some(ref key) = self.config.{{snakeCase configKey}} {
+            req = req.header("{{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"))}}
+        if let Some(ref token) = self.config.{{snakeCase configKey}} {
+            req = req.header("Authorization", format!("Bearer {}", token));
+        }
+{{/if}}
+{{#if (eq type "oauth2")}}
+        if let Some(ref token) = self.config.{{snakeCase configKey}} {
+            req = req.header("Authorization", format!("Bearer {}", token));
+        }
+{{/if}}
+{{#if (eq type "openIdConnect")}}
+        if let Some(ref token) = self.config.{{snakeCase configKey}} {
+            req = req.header("Authorization", format!("Bearer {}", token));
+        }
+{{/if}}
+{{/each}}
+        req
+    }
+
+    fn apply_headers(
+        &self,
+        mut req: RequestBuilder,
+        headers: Option<&[(String, String)]>,
+    ) -> RequestBuilder {
+        if let Some(hdrs) = headers {
+            for (key, value) in hdrs {
+                req = req.header(key.as_str(), value.as_str());
+            }
+        }
+        req
+    }
+
+    async fn execute_with_retry(
+        &self,
+        req: RequestBuilder,
+    ) -> Result<Response, SdkError> {
+        let max_retries = self.config.max_retries;
+        let mut attempt = 0u32;
+
+        loop {
+            let request = req
+                .try_clone()
+                .ok_or_else(|| SdkError::NetworkError("failed to clone request for retry".to_string()))?;
+
+            match request.send().await {
+                Ok(response) => {
+                    let status = response.status();
+
+                    // Retry on server errors (5xx) and 429 Too Many Requests
+                    if status.is_server_error() || status == StatusCode::TOO_MANY_REQUESTS {
+                        if attempt < max_retries {
+                            attempt += 1;
+                            let backoff = Duration::from_millis(
+                                200u64 * 2u64.pow(attempt),
+                            );
+                            tokio::time::sleep(backoff).await;
+                            continue;
+                        }
+                    }
+                    return Ok(response);
+                }
+                Err(e) => {
+                    if attempt < max_retries && e.is_connect() || e.is_timeout() {
+                        attempt += 1;
+                        let backoff = Duration::from_millis(
+                            200u64 * 2u64.pow(attempt),
+                        );
+                        tokio::time::sleep(backoff).await;
+                        continue;
+                    }
+                    return Err(SdkError::NetworkError(e.to_string()));
+                }
+            }
+        }
+    }
+
+    async fn handle_response<T: DeserializeOwned>(
+        &self,
+        response: Response,
+    ) -> Result<T, SdkError> {
+        let status = response.status();
+        let text = response.text().await.map_err(|e| {
+            SdkError::DeserializationError(format!("failed to read response body: {}", e))
+        })?;
+
+        if status.is_success() {
+            serde_json::from_str(&text).map_err(|e| {
+                SdkError::DeserializationError(format!(
+                    "failed to deserialize response (status {}): {}",
+                    status, e
+                ))
+            })
+        } else {
+            Err(self.build_api_error(status, &text))
+        }
+    }
+
+    fn build_api_error(&self, status: StatusCode, body: &str) -> SdkError {
+        // Try to extract structured error info from the JSON body
+        let code = serde_json::from_str::<serde_json::Value>(body)
+            .ok()
+            .and_then(|v| {
+                v.get("code")
+                    .or_else(|| v.get("error"))
+                    .and_then(|c| c.as_str().map(String::from))
+                    .or_else(|| {
+                        v.get("error")
+                            .and_then(|e| e.get("code"))
+                            .and_then(|c| c.as_str().map(String::from))
+                    })
+            });
+
+        let message = serde_json::from_str::<serde_json::Value>(body)
+            .ok()
+            .and_then(|v| {
+                v.get("message")
+                    .or_else(|| v.get("error"))
+                    .and_then(|m| {
+                        if m.is_string() {
+                            m.as_str().map(String::from)
+                        } else {
+                            m.get("message").and_then(|s| s.as_str().map(String::from))
+                        }
+                    })
+            })
+            .unwrap_or_else(|| body.to_string());
+
+        SdkError::ApiError {
+            status: status.as_u16(),
+            code,
+            message,
+            body: body.to_string(),
+        }
+    }
+}
+
+impl std::fmt::Debug for Transport {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Transport")
+            .field("config", &self.config)
+            .finish()
+    }
+}

package/templates/rust/types.hbs

@@ -0,0 +1,142 @@
+use serde::{Deserialize, Serialize};
+
+{{#each schemas}}
+{{#if (and (not ownership) (not isEnum) (not isTypeAlias) (not isUnionType) (not isIntersectionType))}}
+{{#if (or externalImport (eq ownership.kind "external"))}}
+// {{name}} is imported from an external schema package.
+{{else}}
+{{#if description}}
+/// {{description}}
+{{/if}}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+{{#if additionalPropertiesType}}
+{{! Additional properties means we need to use a flattened map }}
+#[serde(rename_all = "camelCase")]
+pub struct {{name}} {
+    {{#each properties}}
+    {{#if description}}
+    /// {{description}}
+    {{/if}}
+    {{#if deprecated}}
+    #[deprecated]
+    {{/if}}
+    {{#if (and nullable (not required))}}
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
+    {{else if nullable}}
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
+    {{else if required}}
+    pub {{snakeCase name}}: {{{rustType type}}},
+    {{else}}
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
+    {{/if}}
+    {{/each}}
+}
+{{else}}
+#[serde(rename_all = "camelCase")]
+pub struct {{name}} {
+    {{#each properties}}
+    {{#if description}}
+    /// {{description}}
+    {{/if}}
+    {{#if deprecated}}
+    #[deprecated]
+    {{/if}}
+    {{#if (and nullable (not required))}}
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
+    {{else if nullable}}
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
+    {{else if required}}
+    pub {{snakeCase name}}: {{{rustType type}}},
+    {{else}}
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
+    {{/if}}
+    {{/each}}
+}
+{{/if}}
+{{/if}}
+{{/if}}
+
+{{#if isEnum}}
+{{#if description}}
+/// {{description}}
+{{/if}}
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+{{#if enumValues}}
+#[serde(rename_all = "camelCase")]
+{{/if}}
+pub enum {{name}} {
+    {{#each enumValues}}
+    #[serde(rename = "{{this}}")]
+    {{pascalCase this}},
+    {{/each}}
+}
+{{/if}}
+
+{{#if isTypeAlias}}
+{{#if description}}
+/// {{description}}
+{{/if}}
+{{#if properties.length}}
+{{! Type alias with shape — emit as struct }}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct {{name}} {
+    {{#each properties}}
+    {{#if description}}
+    /// {{description}}
+    {{/if}}
+    {{#if required}}
+    pub {{snakeCase name}}: {{{rustType type}}},
+    {{else}}
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
+    {{/if}}
+    {{/each}}
+}
+{{else}}
+{{! Simple type alias — skip, referenced by name }}
+// {{name}} is a type alias — referenced inline.
+{{/if}}
+{{/if}}
+
+{{#if isUnionType}}
+{{#if description}}
+/// {{description}}
+{{/if}}
+{{#if unionMembers.length}}
+{{! Union type with named members — emit as enum }}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum {{name}} {
+    {{#each unionMembers}}
+    {{pascalCase this}}({{{rustType this}}}),
+    {{/each}}
+}
+{{/if}}
+{{/if}}
+
+{{#if isIntersectionType}}
+{{#if description}}
+/// {{description}}
+{{/if}}
+{{#if intersectionMembers.length}}
+{{! Intersection type — flatten into a struct combining all members }}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct {{name}} {
+    {{#each intersectionMembers}}
+    // Fields from {{this}} are expected to be inlined by the code generator.
+    {{/each}}
+    // Intersection types require manual field specification.
+    // TODO: inline fields from {{join intersectionMembers ", "}}
+}
+{{/if}}
+{{/if}}
+
+{{/each}}