@apollo-deploy/tesseract 0.9.1 → 1.0.0

package/templates/python/types-errors.hbs

@@ -0,0 +1,75 @@
+"""Error classes for {{moduleName}}."""
+
+from typing import Optional, Dict, Any
+
+
+class SDKError(Exception):
+    """Structured error thrown by all SDK operations."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        code: str,
+        request_id: Optional[str] = None,
+        timestamp: Optional[str] = None,
+        path: Optional[str] = None,
+        method: Optional[str] = None,
+        hint: Optional[str] = None,
+        details: Optional[Any] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.timestamp = timestamp
+        self.path = path
+        self.method = method
+        self.hint = hint
+        self.details = details
+
+    def is_rate_limited(self) -> bool:
+        return self.code == "rate_limit_exceeded"
+
+    def is_auth_error(self) -> bool:
+        return self.code in ("unauthorized", "credential_expired", "credential_revoked")
+
+    def is_forbidden(self) -> bool:
+        return self.code == "forbidden"
+
+    def is_not_found(self) -> bool:
+        return self.code == "not_found"
+
+    def is_validation_error(self) -> bool:
+        return self.code in (
+            "validation_failed",
+            "request_validation_failed",
+            "bad_request",
+            "unprocessable_entity",
+        )
+
+    def is_server_error(self) -> bool:
+        return self.status >= 500
+
+    def is_client_error(self) -> bool:
+        return 400 <= self.status < 500
+
+    def is_retryable(self) -> bool:
+        return (
+            self.code in ("network_error", "gateway_timeout")
+            or self.status == 429
+            or self.status >= 500
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "message": self.message,
+            "status": self.status,
+            "code": self.code,
+            "request_id": self.request_id,
+            "timestamp": self.timestamp,
+            "path": self.path,
+            "method": self.method,
+            "hint": self.hint,
+        }

package/templates/python/types.hbs

@@ -0,0 +1,79 @@
+"""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
+
+
+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 -------------------------------------------
+
+{{#each schemas}}
+{{#if (eq ownership.kind "external")}}
+{{else}}
+{{#if isEnum}}
+class {{name}}(str):
+    """{{#if description}}{{description}}{{else}}Enum for {{name}}{{/if}}"""
+{{#each enumValues}}
+    {{pascalCase this}} = "{{this}}"
+{{/each}}
+
+{{else if isUnionType}}
+{{name}} = Union[{{#each unionMembers}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}]
+"""{{#if description}}{{description}}{{else}}Union type for {{name}}{{/if}}"""
+
+{{else if isTypeAlias}}
+{{name}} = {{additionalPropertiesType}}
+"""{{#if description}}{{description}}{{else}}Type alias for {{name}}{{/if}}"""
+
+{{else}}
+class {{name}}(BaseModel):
+    """{{#if description}}{{description}}{{else}}Schema for {{name}}{{/if}}"""
+{{#each properties}}
+    {{name}}: {{#if nullable}}Optional[{{/if}}{{pythonType type}}{{#if nullable}}] = None{{else}}{{#unless required}} = None{{/unless}}{{/if}}
+{{/each}}
+
+{{/if}}
+{{/if}}
+{{/each}}

package/templates/ruby/Gemfile.hbs

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

package/templates/ruby/client.hbs

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "transport"
+{{#each groups}}
+require_relative "resources/{{fileName}}"
+{{/each}}
+
+module {{pascalCase meta.clientName}}
+  # Configuration for the {{meta.title}} SDK client.
+  class Config
+    # @return [String] the base URL for API requests
+    attr_accessor :base_url
+    # @return [Integer] request timeout in seconds
+    attr_accessor :timeout
+    # @return [Hash] retry configuration
+    attr_accessor :retries
+    # @return [Hash] default headers sent with every request
+    attr_accessor :default_headers
+    {{#each securitySchemes}}
+    # @return [String, nil] credential for {{name}} security scheme
+    attr_accessor :{{camelCase name}}
+    {{/each}}
+
+    # @param base_url [String] the base URL for API requests
+    # @param timeout [Integer] request timeout in seconds (default: 15)
+    # @param retries [Hash] retry configuration
+    # @param default_headers [Hash] headers sent with every request
+    {{#each securitySchemes}}
+    # @param {{camelCase name}} [String, nil] credential for {{name}}
+    {{/each}}
+    def initialize(
+      base_url: '{{meta.baseUrl}}',
+      timeout: 15,
+      retries: { attempts: 3, backoff: 0.4, jitter: true, max_backoff: 30.0 },
+      default_headers: {},
+      {{#each securitySchemes}}
+      {{camelCase name}}: nil,
+      {{/each}}
+      **_
+    )
+      @base_url = base_url
+      @timeout = timeout
+      @retries = retries
+      @default_headers = default_headers
+      {{#each securitySchemes}}
+      @{{camelCase name}} = {{camelCase name}}
+      {{/each}}
+    end
+  end
+
+  # Main client for the {{meta.title}} API.
+  #
+  # Provides access to all API domains as instance methods.
+  class Client
+    {{#each groups}}
+    # @return [{{pascalCase ../meta.clientName}}::{{pascalCase name}}]
+    attr_reader :{{name}}
+    {{/each}}
+
+    # @return [{{pascalCase meta.clientName}}::Config] the client configuration
+    attr_reader :config
+
+    # @return [{{pascalCase meta.clientName}}::Transport] the underlying HTTP transport
+    attr_reader :transport
+
+    # Create a new API client.
+    #
+    # @param config [{{pascalCase meta.clientName}}::Config, Hash, nil]
+    #   Either a Config instance or keyword arguments matching Config#initialize.
+    def initialize(config = nil)
+      @config = if config.is_a?(Config)
+                  config
+                elsif config.is_a?(Hash)
+                  Config.new(**config)
+                else
+                  Config.new
+                end
+
+      @transport = Transport.new(@config)
+
+      {{#each groups}}
+      @{{name}} = {{pascalCase ../meta.clientName}}::{{pascalCase name}}.new(@transport)
+      {{/each}}
+    end
+  end
+end

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