@apollo-deploy/tesseract 1.9.0 → 2.0.0

package/templates/python/types.hbs

@@ -1,79 +1,43 @@
 """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
-
+from __future__ import annotations
 
-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 -------------------------------------------
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Literal, Optional, Union
+from pydantic import BaseModel, ConfigDict, Field
 
 {{#each schemas}}
-{{#if (eq ownership.kind "external")}}
-{{else}}
-{{#if isEnum}}
-class {{name}}(str):
+{{#if external}}
+{{name}} = Any
+
+{{else if isEnum}}
+class {{name}}({{enumBase}}, Enum):
     """{{#if description}}{{description}}{{else}}Enum for {{name}}{{/if}}"""
 {{#each enumValues}}
-    {{pascalCase this}} = "{{this}}"
+    {{name}} = {{{value}}}
 {{/each}}
 
 {{else if isUnionType}}
-{{name}} = Union[{{#each unionMembers}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}]
-"""{{#if description}}{{description}}{{else}}Union type for {{name}}{{/if}}"""
+{{name}} = {{{unionType}}}
 
 {{else if isTypeAlias}}
-{{name}} = {{additionalPropertiesType}}
-"""{{#if description}}{{description}}{{else}}Type alias for {{name}}{{/if}}"""
+{{name}} = {{{aliasType}}}
+
+{{else if isIntersectionType}}
+{{name}} = Dict[str, Any]
 
 {{else}}
 class {{name}}(BaseModel):
     """{{#if description}}{{description}}{{else}}Schema for {{name}}{{/if}}"""
+    model_config = ConfigDict(populate_by_name=True)
+{{#if properties.length}}
 {{#each properties}}
-    {{name}}: {{#if nullable}}Optional[{{/if}}{{pythonType type}}{{#if nullable}}] = None{{else}}{{#unless required}} = None{{/unless}}{{/if}}
+    {{fieldName}}: {{{targetType}}} = {{{fieldDefault}}}
 {{/each}}
-
+{{else}}
+    pass
 {{/if}}
+
 {{/if}}
 {{/each}}

package/templates/ruby/client.hbs

@@ -5,7 +5,7 @@ require_relative "transport"
 require_relative "resources/{{fileName}}"
 {{/each}}
 
-module {{pascalCase meta.clientName}}
+module {{moduleName}}
   # Configuration for the {{meta.title}} SDK client.
   class Config
     # @return [String] the base URL for API requests
@@ -16,6 +16,8 @@ module {{pascalCase meta.clientName}}
     attr_accessor :retries
     # @return [Hash] default headers sent with every request
     attr_accessor :default_headers
+    # @return [Boolean] whether POST/PATCH requests may be retried without an idempotency key
+    attr_accessor :retry_unsafe_requests
     {{#each securitySchemes}}
     # @return [String, nil] credential for {{name}} security scheme
     attr_accessor :{{camelCase name}}
@@ -33,6 +35,7 @@ module {{pascalCase meta.clientName}}
       timeout: 15,
       retries: { attempts: 3, backoff: 0.4, jitter: true, max_backoff: 30.0 },
       default_headers: {},
+      retry_unsafe_requests: false,
       {{#each securitySchemes}}
       {{camelCase name}}: nil,
       {{/each}}
@@ -42,6 +45,7 @@ module {{pascalCase meta.clientName}}
       @timeout = timeout
       @retries = retries
       @default_headers = default_headers
+      @retry_unsafe_requests = retry_unsafe_requests
       {{#each securitySchemes}}
       @{{camelCase name}} = {{camelCase name}}
       {{/each}}
@@ -53,19 +57,19 @@ module {{pascalCase meta.clientName}}
   # Provides access to all API domains as instance methods.
   class Client
     {{#each groups}}
-    # @return [{{pascalCase ../meta.clientName}}::{{pascalCase name}}]
+    # @return [{{../moduleName}}::{{pascalCase name}}]
     attr_reader :{{name}}
     {{/each}}
 
-    # @return [{{pascalCase meta.clientName}}::Config] the client configuration
+    # @return [{{moduleName}}::Config] the client configuration
     attr_reader :config
 
-    # @return [{{pascalCase meta.clientName}}::Transport] the underlying HTTP transport
+    # @return [{{moduleName}}::Transport] the underlying HTTP transport
     attr_reader :transport
 
     # Create a new API client.
     #
-    # @param config [{{pascalCase meta.clientName}}::Config, Hash, nil]
+    # @param config [{{moduleName}}::Config, Hash, nil]
     #   Either a Config instance or keyword arguments matching Config#initialize.
     def initialize(config = nil)
       @config = if config.is_a?(Config)
@@ -79,7 +83,7 @@ module {{pascalCase meta.clientName}}
       @transport = Transport.new(@config)
 
       {{#each groups}}
-      @{{name}} = {{pascalCase ../meta.clientName}}::{{pascalCase name}}.new(@transport)
+      @{{name}} = {{../moduleName}}::{{pascalCase name}}.new(@transport)
       {{/each}}
     end
   end

package/templates/ruby/domain.hbs

@@ -3,13 +3,11 @@
 require_relative "../transport"
 require_relative "../errors"
 
-module {{pascalCase meta.clientName}}
+module {{moduleName}}
   # {{#if description}}{{description}}{{else}}{{name}} API domain{{/if}}
   class {{pascalCase name}}
-    # @return [Transport]
     attr_reader :transport
 
-    # @param transport [Transport]
     def initialize(transport)
       @transport = transport
     end
@@ -21,87 +19,70 @@ module {{pascalCase meta.clientName}}
     {{#if (or summary description)}}
     # {{#if summary}}{{summary}}{{#if description}} — {{description}}{{/if}}{{else}}{{description}}{{/if}}
     {{/if}}
-    {{#if pathParams.length}}
-    # @param {{#each pathParams}}{{snakeCase name}} [{{type}}]{{#unless @last}}, {{/unless}}{{/each}}
-    {{/if}}
+    {{#each pathParams}}
+    # @param {{snakeCase name}} [{{docType}}]
+    {{/each}}
     {{#if requestBody}}
-    # @param body [{{requestBody.type}}{{#unless requestBody.required}}, nil{{/unless}}] request body
+    # @param body [{{requestBodyDocType}}{{#unless requestBody.required}}, nil{{/unless}}] request body
     {{/if}}
-    {{#if (or queryParams.length queryType)}}
-    # @param query [Hash, nil] query parameters
+    {{#if queryParams.length}}
+    # @param query [Hash{{#unless queryRequired}}, nil{{/unless}}] query parameters
     {{/if}}
-    {{#if (and headerParams.length headerType)}}
-    # @param headers [Hash, nil] extra request headers
+    {{#if headerParams.length}}
+    # @param headers [Hash, nil] request headers
     {{/if}}
-    {{#if (and cookieParams.length cookieType)}}
+    {{#if cookieParams.length}}
     # @param cookies [Hash, nil] cookie values
     {{/if}}
-    {{#if timeoutMs}}
-    # @param timeout [Integer, nil] per-request timeout override (seconds)
-    {{/if}}
-    # @raise [{{pascalCase ../meta.clientName}}::SDKError]
-    # @return [{{responseType}}]
-    def {{snakeCase name}}({{#if pathParams.length}}{{#each pathParams}}{{snakeCase name}}:{{#if (or ../requestBody (or ../queryType ../queryParams.length) (or ../headerType ../cookieType))}}, {{/if}}{{/each}}{{/if}}{{#if requestBody}}body: nil{{#if (or ../queryType ../queryParams.length (or ../headerType ../cookieType))}}, {{/if}}{{/if}}{{#if (or queryParams.length queryType)}}query: nil{{#if (or ../headerType ../cookieType)}}, {{/if}}{{/if}}{{#if (and headerParams.length headerType)}}headers: {}{{#if ../cookieType}}, {{/if}}{{/if}}{{#if (and cookieParams.length cookieType)}}cookies: nil{{/if}})
-      {{#if (or pathParams.length headerParams.length cookieParams.length)}}
-      # Build request headers
-      request_headers = {}
-      {{#if (and headerParams.length headerType)}}
-      {{#each headerParams}}
-      request_headers["{{originalName}}"] = headers[:{{snakeCase name}}].to_s if headers[:{{snakeCase name}}]
-      {{/each}}
-      {{/if}}
-      {{#if (and cookieParams.length cookieType)}}
-      if cookies
-        cookie_pairs = []
-        {{#each cookieParams}}
-        cookie_pairs << "{{originalName}}=#{::URI.encode_www_form_component(cookies[:{{snakeCase name}}].to_s)}" if cookies[:{{snakeCase name}}]
-        {{/each}}
-        request_headers["Cookie"] = cookie_pairs.join("; ") unless cookie_pairs.empty?
-      end
-      {{/if}}
-      {{/if}}
-
-      {{#if pathParams.length}}
-      # Path parameter substitution
+    # @raise [{{../moduleName}}::SDKError]
+    # @return [{{responseDocType}}]
+    def {{methodName}}({{{signature}}})
+{{#if pathParams.length}}
       path_params = {
-        {{#each pathParams}}
-        {{originalName}}: {{snakeCase name}},
-        {{/each}}
+{{#each pathParams}}
+        {{name}}: {{parameterName}},
+{{/each}}
       }
-      {{/if}}
-
-      {{#if queryParams.length}}
-      # Query parameters
+{{/if}}
+{{#if queryParams.length}}
       query_params = {}
-      {{#each queryParams}}
-      query_params["{{originalName}}"] = query[:{{snakeCase name}}] if query && query.key?(:{{snakeCase name}})
-      {{/each}}
+{{#each queryParams}}
+      query_params["{{originalName}}"] = query[:{{parameterName}}] if query && query.key?(:{{parameterName}})
+{{/each}}
       query_params = nil if query_params.empty?
-      {{else if queryType}}
-      # Free-form query parameters
-      query_params = query
-      {{/if}}
+{{/if}}
+{{#if (or headerParams.length cookieParams.length)}}
+      request_headers = {}
+{{#each headerParams}}
+      request_headers["{{originalName}}"] = headers[:{{parameterName}}].to_s if headers && headers.key?(:{{parameterName}})
+{{/each}}
+{{#if cookieParams.length}}
+      cookie_pairs = []
+{{#each cookieParams}}
+      cookie_pairs << "{{originalName}}=#{::URI.encode_www_form_component(cookies[:{{parameterName}}].to_s)}" if cookies && cookies.key?(:{{parameterName}})
+{{/each}}
+      request_headers["Cookie"] = cookie_pairs.join("; ") unless cookie_pairs.empty?
+{{/if}}
+{{/if}}
 
-      transport.request(
-        method: :{{httpMethod}},
+      transport.{{#if isEventStream}}stream{{else}}request{{/if}}(
+        method: :{{rubyHttpMethod}},
         path: "{{path}}",
-        {{#if pathParams.length}}
+{{#if pathParams.length}}
         path_params: path_params,
-        {{/if}}
-        {{#if requestBody}}
+{{/if}}
+{{#if requestBody}}
         body: body,
-        {{/if}}
-        {{#if (or queryParams.length queryType)}}
+{{/if}}
+{{#if queryParams.length}}
         query: query_params,
-        {{/if}}
-        {{#if (or (and headerParams.length headerType) (and cookieParams.length cookieType))}}
+{{/if}}
+{{#if (or headerParams.length cookieParams.length)}}
         headers: request_headers,
-        {{/if}}
-        {{#if (neq requestBody.contentType "application/json")}}
-        {{#if requestBody.contentType}}
+{{/if}}
+{{#if requestBody.contentType}}
         content_type: "{{requestBody.contentType}}",
-        {{/if}}
-        {{/if}}
+{{/if}}
       )
     end
 

package/templates/ruby/errors.hbs

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module {{pascalCase meta.clientName}}
+module {{moduleName}}
   # Structured error raised on API and network failures.
   #
   # Inherits from StandardError and provides structured access to error
@@ -10,7 +10,7 @@ module {{pascalCase meta.clientName}}
   # @example Basic error handling
   #   begin
   #     client.users.get_user(id: "123")
-  #   rescue {{pascalCase meta.clientName}}::SDKError => e
+  #   rescue {{moduleName}}::SDKError => e
   #     puts "Error #{e.status}: #{e.message} (#{e.code})"
   #     puts "Request ID: #{e.request_id}" if e.request_id
   #
@@ -122,7 +122,7 @@ module {{pascalCase meta.clientName}}
     def retryable?
       @code == "network_error" ||
         @code == "gateway_timeout" ||
-        @status == 429 ||
+        [408, 425, 429].include?(@status) ||
         @status >= 500
     end
 

package/templates/ruby/gemspec.hbs

@@ -4,26 +4,19 @@ require_relative "lib/{{snakeModule}}/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "{{gemName}}"
-  spec.version       = {{pascalCase snakeModule}}::VERSION
+  spec.version       = {{moduleName}}::VERSION
   spec.authors       = ["API SDK Generator"]
   spec.email         = ["sdk@example.com"]
 
-  spec.summary       = "{{#if meta.description}}{{meta.description}}{{else}}Ruby SDK for {{meta.title}}{{/if}}"
+  spec.summary       = "Ruby SDK for {{meta.title}}"
   spec.description   = "{{#if meta.description}}{{meta.description}}{{else}}A Ruby client library for the {{meta.title}} API.{{/if}}"
-  spec.homepage      = "https://github.com/example/{{gemName}}"
   spec.license       = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
 
-  spec.metadata["homepage_uri"]    = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/example/{{gemName}}"
-  spec.metadata["changelog_uri"]   = "https://github.com/example/{{gemName}}/blob/main/CHANGELOG.md"
-
-  spec.files = Dir.glob("lib/**/*.rb") + %w[README.md LICENSE Gemfile]
+  spec.files = Dir.glob("lib/**/*.rb") + Dir.glob("docs/**/*.md") + %w[README.md LICENSE Gemfile]
   spec.require_paths = ["lib"]
 
   spec.add_dependency "faraday", "~> 2.0"
-  spec.add_dependency "json"
-
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "webmock", "~> 3.0"

package/templates/ruby/index.hbs

@@ -9,7 +9,7 @@ require_relative "{{snakeModule}}/client"
 require_relative "{{../snakeModule}}/resources/{{fileName}}"
 {{/each}}
 
-module {{pascalCase snakeModule}}
+module {{moduleName}}
   # Factory method to create a new client instance.
   #
   # @param base_url [String] the base URL for the API
@@ -25,7 +25,7 @@ module {{pascalCase snakeModule}}
   {{#if hasSSE}}
   # @param sse_client [Object, nil] optional SSE client implementation
   {{/if}}
-  # @return [{{pascalCase meta.clientName}}::Client]
+  # @return [{{moduleName}}::Client]
   def self.create_client(
     base_url: '{{meta.baseUrl}}',
     timeout: 15,
@@ -38,7 +38,7 @@ module {{pascalCase snakeModule}}
     {{/if}}
     **extra
   )
-    {{pascalCase meta.clientName}}::Client.new(
+    {{moduleName}}::Client.new(
       base_url: base_url,
       timeout: timeout,
       retries: retries,

package/templates/ruby/readme.hbs

@@ -1,113 +1,76 @@
 # {{meta.title}} Ruby SDK
 
-{{#if meta.description}}
-{{meta.description}}
+{{#if meta.description}}{{meta.description}}{{else}}Ruby client for the {{meta.title}} API.{{/if}}
 
-{{/if}}
-> This SDK was automatically generated by [Tesseract](https://www.npmjs.com/package/@apollo-deploy/tesseract).
+> Generated by [Tesseract](https://www.npmjs.com/package/@apollo-deploy/tesseract). Generated source files should not be edited manually.
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
 gem '{{gemName}}'
 ```
 
-And then execute:
-
 ```bash
 bundle install
 ```
 
-Or install it yourself as:
-
-```bash
-gem install {{gemName}}
-```
-
-## Quick Start
+## Quick start
 
 ```ruby
 require '{{gemName}}'
 
-client = {{pascalCase meta.clientName}}::Client.new(
+client = {{moduleName}}::Client.new(
   base_url: '{{meta.baseUrl}}',
 {{#each securitySchemes}}
-  {{camelCase name}}: 'your-{{kebabCase name}}-credential',
+  {{camelCase name}}: ENV['{{upperCase (snakeCase name)}}'],
 {{/each}}
+  timeout: 15
 )
 
-# Make API calls
-result = client.{{groups.[0].name}}.{{groups.[0].operations.[0].name}}
+{{#if groups.length}}
+api = client.{{groups.[0].name}}
+{{/if}}
 ```
 
-## Configuration
+## Configuration and reliability
+
+The transport provides bounded timeouts, exponential-backoff retries, rate-limit handling, default headers, and structured `SDKError` values. Unsafe requests are retried only when explicitly enabled or made idempotent.
 
 ```ruby
-client = {{pascalCase meta.clientName}}::Client.new(
-  base_url: '{{meta.baseUrl}}',
-{{#each securitySchemes}}
-  {{camelCase name}}: ENV['{{upperCase (snakeCase name)}}'],
-{{/each}}
-  timeout: 30,               # seconds
-  retries: { attempts: 3, backoff: 0.4, jitter: true }
+client = {{moduleName}}::Client.new(
+  timeout: 30,
+  retries: {
+    attempts: 3,
+    backoff: 0.4,
+    jitter: true,
+    max_backoff: 30.0
+  },
+  default_headers: { 'X-Application' => 'my-service' }
 )
 ```
 
-## API Reference
+## Documentation
 
-{{#each groups}}
-### {{pascalCase name}}
-
-{{#if description}}
-{{description}}
-
-{{/if}}
-| Method | HTTP | Path | Description |
-|--------|------|------|-------------|
-{{#each operations}}
-| `{{snakeCase name}}` | {{httpMethod}} | `{{path}}` | {{#if summary}}{{summary}}{{else}}-{{/if}} |
-{{/each}}
-
-{{/each}}
+- [Documentation index](./docs/README.md)
+- [Generated types](./docs/types.md)
 
-## Types
-
-{{#each schemas}}
-{{#if isEnum}}
-- `{{pascalCase name}}` — module with constants: {{#each enumValues}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
-{{else if isTypeAlias}}
-- `{{pascalCase name}}` — type alias
-{{else}}
-- `{{pascalCase name}}`{{#if description}} — {{description}}{{/if}}
-{{/if}}
+| Domain | Description |
+|---|---|
+{{#each groups}}
+| [{{pascalCase name}}](./docs/domains/{{fileName}}.md) | {{#if description}}{{description}}{{else}}{{name}} operations{{/if}} |
 {{/each}}
 
-## Error Handling
+## Error handling
 
 ```ruby
 begin
-  result = client.some_api.some_method
-rescue {{pascalCase meta.clientName}}::SDKError => e
-  puts "Error #{e.status}: #{e.message} (#{e.code})"
-  puts "Request ID: #{e.request_id}" if e.request_id
-
-  if e.rate_limited?
-    sleep 1
-    retry
-  end
-
+  # Call a domain operation.
+rescue {{moduleName}}::SDKError => error
+  warn "#{error.status} #{error.code} request=#{error.request_id}"
   raise
 end
 ```
 
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies.
-Then, run `rake spec` to run the tests.
-You can also run `bin/console` for an interactive prompt.
-
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT