@apollo-deploy/tesseract 0.9.1 → 1.2.0

package/templates/ruby/domain.hbs

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "../transport"
+require_relative "../errors"
+
+module {{pascalCase meta.clientName}}
+  # {{#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
+
+{{#each operations}}
+    {{#if deprecated}}
+    # @deprecated {{#if deprecationMessage}}{{deprecationMessage}}{{else}}Use a replacement method.{{/if}}
+    {{/if}}
+    {{#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}}
+    {{#if requestBody}}
+    # @param body [{{requestBody.type}}{{#unless requestBody.required}}, nil{{/unless}}] request body
+    {{/if}}
+    {{#if (or queryParams.length queryType)}}
+    # @param query [Hash, nil] query parameters
+    {{/if}}
+    {{#if (and headerParams.length headerType)}}
+    # @param headers [Hash, nil] extra request headers
+    {{/if}}
+    {{#if (and cookieParams.length cookieType)}}
+    # @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
+      path_params = {
+        {{#each pathParams}}
+        {{originalName}}: {{snakeCase name}},
+        {{/each}}
+      }
+      {{/if}}
+
+      {{#if queryParams.length}}
+      # Query parameters
+      query_params = {}
+      {{#each queryParams}}
+      query_params["{{originalName}}"] = query[:{{snakeCase name}}] if query && query.key?(:{{snakeCase name}})
+      {{/each}}
+      query_params = nil if query_params.empty?
+      {{else if queryType}}
+      # Free-form query parameters
+      query_params = query
+      {{/if}}
+
+      transport.request(
+        method: :{{httpMethod}},
+        path: "{{path}}",
+        {{#if pathParams.length}}
+        path_params: path_params,
+        {{/if}}
+        {{#if requestBody}}
+        body: body,
+        {{/if}}
+        {{#if (or queryParams.length queryType)}}
+        query: query_params,
+        {{/if}}
+        {{#if (or (and headerParams.length headerType) (and cookieParams.length cookieType))}}
+        headers: request_headers,
+        {{/if}}
+        {{#if (neq requestBody.contentType "application/json")}}
+        {{#if requestBody.contentType}}
+        content_type: "{{requestBody.contentType}}",
+        {{/if}}
+        {{/if}}
+      )
+    end
+
+{{/each}}
+  end
+end

package/templates/ruby/errors.hbs

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module {{pascalCase meta.clientName}}
+  # Structured error raised on API and network failures.
+  #
+  # Inherits from StandardError and provides structured access to error
+  # details including status code, error code, request ID, and convenience
+  # methods for common error classifications.
+  #
+  # @example Basic error handling
+  #   begin
+  #     client.users.get_user(id: "123")
+  #   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
+  #
+  #     if e.server_error?
+  #       # Log and alert
+  #     end
+  #   end
+  class SDKError < StandardError
+    # @return [String] machine-readable error code (e.g. "not_found", "rate_limit_exceeded")
+    attr_reader :code
+
+    # @return [Integer] HTTP status code (0 for network errors)
+    attr_reader :status
+
+    # @return [String, nil] unique request identifier from the server
+    attr_reader :request_id
+
+    # @return [String, nil] ISO 8601 timestamp of error occurrence
+    attr_reader :timestamp
+
+    # @return [String, nil] request path that caused the error
+    attr_reader :path
+
+    # @return [String, nil] HTTP method that caused the error
+    attr_reader :method
+
+    # @return [String, nil] helpful hint for resolving the error
+    attr_reader :hint
+
+    # @return [Hash, nil] structured error details
+    attr_reader :details
+
+    # Create a new SDKError.
+    #
+    # @param message [String] human-readable error message
+    # @param status [Integer] HTTP status code (0 for network errors)
+    # @param code [String] machine-readable error code
+    # @param request_id [String, nil] server-provided request ID
+    # @param timestamp [String, nil] error timestamp
+    # @param path [String, nil] request path
+    # @param method [String, nil] HTTP method
+    # @param hint [String, nil] resolution hint
+    # @param details [Hash, nil] structured error details
+    def initialize(
+      message,
+      status = 0,
+      code = "unknown_error",
+      request_id: nil,
+      timestamp: nil,
+      path: nil,
+      method: nil,
+      hint: nil,
+      details: nil
+    )
+      super(message)
+
+      @code = code
+      @status = status
+      @request_id = request_id
+      @timestamp = timestamp
+      @path = path
+      @method = method
+      @hint = hint
+      @details = details
+    end
+
+    # @return [Boolean] true if the error is a rate limit (HTTP 429)
+    def rate_limited?
+      @code == "rate_limit_exceeded" || @status == 429
+    end
+
+    # @return [Boolean] true if the error is authentication-related
+    def auth_error?
+      %w[unauthorized credential_expired credential_revoked].include?(@code)
+    end
+
+    # @return [Boolean] true if the error is a permission error (HTTP 403)
+    def forbidden?
+      @code == "forbidden" || @status == 403
+    end
+
+    # @return [Boolean] true if the resource was not found (HTTP 404)
+    def not_found?
+      @code == "not_found" || @status == 404
+    end
+
+    # @return [Boolean] true if the error is a validation error
+    def validation_error?
+      %w[validation_failed request_validation_failed bad_request unprocessable_entity].include?(@code) ||
+        @status == 422
+    end
+
+    # @return [Boolean] true if status is 5xx (server error)
+    def server_error?
+      @status >= 500
+    end
+
+    # @return [Boolean] true if status is 4xx (client error)
+    def client_error?
+      @status >= 400 && @status < 500
+    end
+
+    # @return [Boolean] true if this error is safe to retry
+    def retryable?
+      @code == "network_error" ||
+        @code == "gateway_timeout" ||
+        @status == 429 ||
+        @status >= 500
+    end
+
+    # @return [Hash] a hash representation for logging and serialization
+    def to_h
+      {
+        name: "SDKError",
+        message: message,
+        status: @status,
+        code: @code,
+        request_id: @request_id,
+        timestamp: @timestamp,
+        path: @path,
+        method: @method,
+        hint: @hint,
+        details: @details
+      }.compact
+    end
+
+    # @return [String] JSON representation for logging
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end

package/templates/ruby/gemspec.hbs

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "lib/{{snakeModule}}/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "{{gemName}}"
+  spec.version       = {{pascalCase snakeModule}}::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.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.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"
+end

package/templates/ruby/index.hbs

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "{{snakeModule}}/version"
+require_relative "{{snakeModule}}/errors"
+require_relative "{{snakeModule}}/transport"
+require_relative "{{snakeModule}}/types"
+require_relative "{{snakeModule}}/client"
+{{#each groups}}
+require_relative "{{../snakeModule}}/resources/{{fileName}}"
+{{/each}}
+
+module {{pascalCase snakeModule}}
+  # Factory method to create a new client instance.
+  #
+  # @param base_url [String] the base URL for the API
+  # @param timeout [Integer] request timeout in seconds (default: 15)
+  # @param retries [Hash] retry configuration
+  # @option retries [Integer] :attempts (3)
+  # @option retries [Float] :backoff (0.4)
+  # @option retries [Boolean] :jitter (true)
+  # @option retries [Float] :max_backoff (30.0)
+  {{#each securitySchemes}}
+  # @param {{camelCase name}} [String, nil] {{#if description}}{{description}}{{else}}credential for {{name}}{{/if}}
+  {{/each}}
+  {{#if hasSSE}}
+  # @param sse_client [Object, nil] optional SSE client implementation
+  {{/if}}
+  # @return [{{pascalCase meta.clientName}}::Client]
+  def self.create_client(
+    base_url: '{{meta.baseUrl}}',
+    timeout: 15,
+    retries: { attempts: 3, backoff: 0.4, jitter: true, max_backoff: 30.0 },
+    {{#each securitySchemes}}
+    {{camelCase name}}: nil,
+    {{/each}}
+    {{#if hasSSE}}
+    sse_client: nil,
+    {{/if}}
+    **extra
+  )
+    {{pascalCase meta.clientName}}::Client.new(
+      base_url: base_url,
+      timeout: timeout,
+      retries: retries,
+      {{#each securitySchemes}}
+      {{camelCase name}}: {{camelCase name}},
+      {{/each}}
+      {{#if hasSSE}}
+      sse_client: sse_client,
+      {{/if}}
+      **extra
+    )
+  end
+end

package/templates/ruby/readme.hbs

@@ -0,0 +1,113 @@
+# {{meta.title}} Ruby SDK
+
+{{#if meta.description}}
+{{meta.description}}
+
+{{/if}}
+> This SDK was automatically generated by [Tesseract](https://www.npmjs.com/package/@apollo-deploy/tesseract).
+
+## 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
+
+```ruby
+require '{{gemName}}'
+
+client = {{pascalCase meta.clientName}}::Client.new(
+  base_url: '{{meta.baseUrl}}',
+{{#each securitySchemes}}
+  {{camelCase name}}: 'your-{{kebabCase name}}-credential',
+{{/each}}
+)
+
+# Make API calls
+result = client.{{groups.[0].name}}.{{groups.[0].operations.[0].name}}
+```
+
+## Configuration
+
+```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 }
+)
+```
+
+## API Reference
+
+{{#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}}
+
+## 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}}
+{{/each}}
+
+## 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
+
+  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).

package/templates/ruby/transport.hbs

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require_relative "errors"
+
+module {{pascalCase meta.clientName}}
+  # HTTP transport layer built on Faraday.
+  class Transport
+    attr_reader :config
+    attr_reader :connection
+
+    def initialize(config)
+      @config = config
+      @connection = Faraday.new(url: config.base_url) do |f|
+        f.request :json
+        f.response :raise_error
+        f.options.timeout = config.timeout
+        f.options.open_timeout = [config.timeout / 3, 2].max
+        config.default_headers.each do |key, value|
+          f.headers[key] = value
+        end
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def request(method:, path:, path_params: {}, query: nil, body: nil, headers: {}, content_type: nil)
+      url = build_url(path, path_params)
+      attempts = 0
+      max_attempts = [(@config.retries[:attempts] || 3), 1].max
+      backoff = @config.retries[:backoff] || 0.4
+      jitter = @config.retries.fetch(:jitter, true)
+      max_backoff = @config.retries[:max_backoff] || 30.0
+      begin
+        attempts += 1
+        response = @connection.run_request(
+          method.to_sym, url, body, build_headers(headers, content_type)
+        ) do |req|
+          req.params.merge!(query) if query && !query.empty?
+        end
+        parse_response(response)
+      rescue Faraday::Error => e
+        raise map_error(e, method: method, path: path) unless should_retry?(e, attempts, max_attempts)
+        sleep(retry_delay(backoff, attempts, jitter, max_backoff))
+        retry
+      end
+    end
+
+    def get(path:, path_params: {}, query: nil, headers: {})
+      request(method: :get, path: path, path_params: path_params, query: query, headers: headers)
+    end
+
+    def post(path:, body: nil, path_params: {}, query: nil, headers: {}, content_type: nil)
+      request(method: :post, path: path, body: body, path_params: path_params,
+              query: query, headers: headers, content_type: content_type)
+    end
+
+    def put(path:, body: nil, path_params: {}, query: nil, headers: {}, content_type: nil)
+      request(method: :put, path: path, body: body, path_params: path_params,
+              query: query, headers: headers, content_type: content_type)
+    end
+
+    def patch(path:, body: nil, path_params: {}, query: nil, headers: {}, content_type: nil)
+      request(method: :patch, path: path, body: body, path_params: path_params,
+              query: query, headers: headers, content_type: content_type)
+    end
+
+    def delete(path:, path_params: {}, query: nil, headers: {})
+      request(method: :delete, path: path, path_params: path_params, query: query, headers: headers)
+    end
+
+    private
+
+    def build_url(path, path_params)
+      return path if path_params.empty?
+      path.gsub(/\{(\w+)\}/) do |_match|
+        key = ::Regexp.last_match(1)
+        value = path_params[key.to_sym] || path_params[key]
+        value.nil? ? _match : value.to_s
+      end
+    end
+
+    def build_headers(extra_headers = {}, content_type = nil)
+      headers = {}
+      if content_type
+        headers["Content-Type"] = content_type
+      end
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+{{#if (eq in "header")}}
+      headers["{{paramName}}"] = @config.{{camelCase name}} if @config.{{camelCase name}}
+{{/if}}
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
+      headers["Authorization"] = "Bearer " + (@config.{{camelCase name}} || "") if @config.{{camelCase name}}
+{{/if}}
+{{#if (eq type "oauth2")}}
+      headers["Authorization"] = "Bearer " + (@config.{{camelCase name}} || "") if @config.{{camelCase name}}
+{{/if}}
+{{#if (eq type "openIdConnect")}}
+      headers["Authorization"] = "Bearer " + (@config.{{camelCase name}} || "") if @config.{{camelCase name}}
+{{/if}}
+{{/each}}
+      headers.merge!(extra_headers)
+      headers
+    end
+
+    def parse_response(response)
+      body = response.body
+      return nil if body.nil? || (body.is_a?(String) && body.strip.empty?)
+      if body.is_a?(String)
+        begin
+          JSON.parse(body)
+        rescue JSON::ParserError
+          body
+        end
+      else
+        body
+      end
+    end
+
+    def map_error(error, method:, path:)
+      case error
+      when Faraday::TimeoutError
+        SDKError.new("Request timed out", 0, "network_error", method: method, path: path)
+      when Faraday::ConnectionFailed
+        SDKError.new("Connection failed: " + error.message, 0, "network_error", method: method, path: path)
+      when Faraday::ResourceNotFound
+        SDKError.new("Not found: " + error.message, 404, "not_found", method: method, path: path)
+      when Faraday::ClientError
+        status = error.response&.[](:status) || 400
+        begin
+          body = error.response&.[](:body)
+          envelope = body.is_a?(String) ? JSON.parse(body) : body
+          if envelope.is_a?(Hash)
+            SDKError.new(
+              envelope["message"] || envelope["error"] || "Request failed",
+              status,
+              envelope["error"] || envelope["code"] || "unknown_error",
+              request_id: envelope["request_id"],
+              method: method, path: path
+            )
+          else
+            SDKError.new("Request failed with status " + status.to_s, status, "unknown_error", method: method, path: path)
+          end
+        rescue
+          SDKError.new("Request failed with status " + status.to_s, status, "unknown_error", method: method, path: path)
+        end
+      when Faraday::ServerError
+        status = error.response&.[](:status) || 500
+        SDKError.new("Server error: " + error.message, status, "internal_server_error", method: method, path: path)
+      else
+        SDKError.new(error.message, 0, "unknown_error", method: method, path: path)
+      end
+    end
+
+    def should_retry?(_error, attempts, max_attempts)
+      return false if attempts >= max_attempts
+      case _error
+      when Faraday::TimeoutError, Faraday::ConnectionFailed, Faraday::ServerError
+        true
+      when Faraday::ClientError
+        status = _error.response&.[](:status)
+        status == 429
+      else
+        false
+      end
+    end
+
+    def retry_delay(base, attempt, jitter, max_backoff)
+      delay = base * (2**(attempt - 1))
+      delay = max_backoff if delay > max_backoff
+      delay *= (0.5 + rand * 0.5) if jitter
+      delay
+    end
+  end
+end