hatchet-sdk 0.0.0 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04cba5845adc6fdaa4fe8211dcf3326ff8e029d458ea80db7c9aa8018092a466
-  data.tar.gz: 54e7411d0da2caba1198049225642b1242fe25838d62d1b70560fefdd9bc30f5
+  metadata.gz: 415716e0955c26837a2887bd5703497b2bda92f167593742747aff057d4db77a
+  data.tar.gz: 510bc99100f79cb590eafc874b0e4114035bec15cff11f77229a6b59a497ad70
 SHA512:
-  metadata.gz: cd5c9791787389f7a844f2cb61f9394b31ee8212a8fde4a06701be212683536de20cf78fa5db8c55a8ab03fcab09c190101ef6dd084720a92b66f739d0f2016d
-  data.tar.gz: 86d51a2da75ccd5cdae6c9fd01fb6e18e8956227661f34cd892ad26b517e51ce4add58b93fd212eec92da7621a7c4aa729746ebe39804d79dd8d5ed278f0c62c
+  metadata.gz: 174e40cbb3d3c5470c3ae2aaa3a148048240fd4665519177e33d2dddd4f567c3105ba01dad812eefa586fda560c353395689a3f0f228e19c9a554a670d2508df
+  data.tar.gz: ae343d08ea3648c703a7d4f66b7bd23b0527dca64ee6beb0a4fee66c300c8ac95d42ed50f30155a5372cb6ebf0bd663c7c4fa8776c13a09b31250c56e8863958

data/CLAUDE.md

@@ -4,7 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is the Ruby SDK for Hatchet (gem name: hatchet-sdk), currently in early development (version 0.0.0). The project follows standard Ruby gem conventions with a simple structure containing a main `Hatchet` module with a `Client` class for API key authentication.
+This is the Ruby SDK for Hatchet (gem name: hatchet-sdk), currently in early development (version 0.0.0). The project follows standard Ruby gem conventions with a simple structure containing a main `Hatchet` module with a `Client` class for JWT token authentication.
+
+The SDK includes comprehensive documentation and type signatures for excellent IDE support, including parameter hints, auto-completion, and type checking.
 
 ## Common Commands
 
@@ -25,18 +27,53 @@ This is the Ruby SDK for Hatchet (gem name: hatchet-sdk), currently in early dev
 **Gem Management:**
 - `bundle exec rake release` - Release new version (updates version, creates git tag, pushes to rubygems)
 
+**Documentation:**
+- `yard doc` - Generate YARD documentation (if yard gem is installed)
+- `rbs validate` - Validate RBS type signatures for syntax errors
+
 ## Architecture
 
 **Core Structure:**
 - `lib/hatchet-sdk.rb` - Main entry point, defines `Hatchet` module with `Error` and `Client` classes
 - `lib/hatchet/version.rb` - Version constant
-- `spec/` - RSpec tests with monkey patching disabled
-- `sig/hatchet-sdk.rbs` - Ruby type signatures
+- `lib/hatchet/config.rb` - Configuration classes with comprehensive JWT token support
+- `spec/` - RSpec tests with monkey patching disabled (36+ test cases)
+- `sig/hatchet-sdk.rbs` - Ruby type signatures for IDE integration
 
 **Key Classes:**
-- `Hatchet::Client` - Main client class that accepts an API key for authentication
+- `Hatchet::Client` - Main client class that accepts JWT token for authentication
+- `Hatchet::Config` - Configuration class supporting multiple sources (params, env vars, JWT payload)
+- `Hatchet::TLSConfig` - TLS configuration for secure connections
+- `Hatchet::HealthcheckConfig` - Worker health monitoring configuration  
+- `Hatchet::OpenTelemetryConfig` - Observability configuration
 - `Hatchet::Error` - Base error class for gem-specific exceptions
 
+**Configuration Sources (priority order):**
+1. Explicit constructor parameters (highest priority)
+2. Environment variables (`HATCHET_CLIENT_*`)
+3. JWT token payload (tenant_id extracted from 'sub' field)
+4. Default values (lowest priority)
+
+**Documentation & IDE Support:**
+- **YARD documentation** - Comprehensive JSDoc-style comments with examples
+- **RBS type signatures** - Complete type definitions for IDE parameter hints
+- **Sorbet compatibility** - Tagged with `# typed: strict` for type checking
+- IDEs with Ruby LSP/RubyMine will show parameter hints, auto-completion, and types
+
 The codebase uses frozen string literals and follows Ruby 3.1+ requirements.
 
+## Development Notes
+
+**When adding new configuration options:**
+1. Add the parameter to `Config#initialize` method
+2. Update the `@option` YARD documentation in both `Client` and `Config` classes  
+3. Add the parameter to RBS type signatures in `sig/hatchet-sdk.rbs`
+4. Add comprehensive test coverage in `spec/hatchet/config_spec.rb`
+5. Update this CLAUDE.md file with any architectural changes
+
+**Testing JWT token functionality:**
+- Use `Base64.encode64('{"sub":"tenant-id"}').gsub(/\n/, "").gsub(/=+$/, "")` to create test JWT payloads
+- The config extracts tenant_id from the 'sub' field in JWT tokens
+- Test both explicit tenant_id override and JWT extraction scenarios
+
 Keep the CLAUDE.md instructions up to date as the project continues to develop.

data/lib/hatchet/config.rb

@@ -0,0 +1,482 @@
+# frozen_string_literal: true
+
+require "logger"
+require "json"
+require "base64"
+
+module Hatchet
+  # TLS configuration for client connections
+  #
+  # @example Basic TLS setup
+  #   tls = TLSConfig.new(strategy: "tls", server_name: "api.hatchet.com")
+  #
+  # @example Custom certificate setup
+  #   tls = TLSConfig.new(
+  #     strategy: "mtls",
+  #     cert_file: "/path/to/client.crt",
+  #     key_file: "/path/to/client.key",
+  #     root_ca_file: "/path/to/ca.crt"
+  #   )
+  class TLSConfig
+    # @!attribute strategy
+    #   @return [String] TLS strategy ("tls", "mtls", "insecure")
+    # @!attribute cert_file
+    #   @return [String, nil] Path to client certificate file for mTLS
+    # @!attribute key_file
+    #   @return [String, nil] Path to client private key file for mTLS
+    # @!attribute root_ca_file
+    #   @return [String, nil] Path to root CA certificate file
+    # @!attribute server_name
+    #   @return [String] Server name for TLS verification
+    attr_accessor :strategy, :cert_file, :key_file, :root_ca_file, :server_name
+
+    # Initialize TLS configuration
+    #
+    # @param options [Hash] TLS configuration options
+    # @option options [String] :strategy TLS strategy (default: "tls")
+    # @option options [String] :cert_file Path to client certificate file
+    # @option options [String] :key_file Path to client private key file
+    # @option options [String] :root_ca_file Path to root CA certificate file
+    # @option options [String] :server_name Server name for TLS verification
+    def initialize(**options)
+      @strategy = options[:strategy] || env_var("HATCHET_CLIENT_TLS_STRATEGY") || "tls"
+      @cert_file = options[:cert_file] || env_var("HATCHET_CLIENT_TLS_CERT_FILE")
+      @key_file = options[:key_file] || env_var("HATCHET_CLIENT_TLS_KEY_FILE")
+      @root_ca_file = options[:root_ca_file] || env_var("HATCHET_CLIENT_TLS_ROOT_CA_FILE")
+      @server_name = options[:server_name] || env_var("HATCHET_CLIENT_TLS_SERVER_NAME") || ""
+    end
+
+    private
+
+    def env_var(name)
+      ENV[name]
+    end
+  end
+
+  # Healthcheck configuration for worker health monitoring
+  #
+  # @example Enable healthcheck on custom port
+  #   healthcheck = HealthcheckConfig.new(enabled: true, port: 8080)
+  class HealthcheckConfig
+    # @!attribute port
+    #   @return [Integer] Port number for healthcheck endpoint
+    # @!attribute enabled
+    #   @return [Boolean] Whether healthcheck is enabled
+    attr_accessor :port, :enabled
+
+    # Initialize healthcheck configuration
+    #
+    # @param options [Hash] Healthcheck configuration options
+    # @option options [Integer] :port Port number for healthcheck endpoint (default: 8001)
+    # @option options [Boolean] :enabled Whether healthcheck is enabled (default: false)
+    def initialize(**options)
+      @port = parse_int(options[:port] || env_var("HATCHET_CLIENT_WORKER_HEALTHCHECK_PORT")) || 8001
+      @enabled = parse_bool(options[:enabled] || env_var("HATCHET_CLIENT_WORKER_HEALTHCHECK_ENABLED")) || false
+    end
+
+    private
+
+    def env_var(name)
+      ENV[name]
+    end
+
+    def parse_int(value)
+      return nil if value.nil?
+      return value if value.is_a?(Integer)
+      return nil if value.respond_to?(:empty?) && value.empty?
+
+      Integer(value)
+    rescue ArgumentError
+      nil
+    end
+
+    def parse_bool(value)
+      return nil if value.nil?
+      return value if [true, false].include?(value)
+
+      %w[true 1 yes on].include?(value.to_s.downcase)
+    end
+  end
+
+  # OpenTelemetry configuration for observability
+  #
+  # @example Exclude sensitive attributes from telemetry
+  #   otel = OpenTelemetryConfig.new(excluded_attributes: ["password", "api_key"])
+  class OpenTelemetryConfig
+    # @!attribute excluded_attributes
+    #   @return [Array<String>] List of attribute names to exclude from telemetry
+    attr_accessor :excluded_attributes
+
+    # Initialize OpenTelemetry configuration
+    #
+    # @param options [Hash] OpenTelemetry configuration options
+    # @option options [Array<String>] :excluded_attributes List of attribute names to exclude from telemetry
+    def initialize(**options)
+      @excluded_attributes = options[:excluded_attributes] ||
+                         parse_json_array(
+                           env_var("HATCHET_CLIENT_OPENTELEMETRY_EXCLUDED_ATTRIBUTES")
+                         ) || []
+    end
+
+    private
+
+    def env_var(name)
+      ENV[name]
+    end
+
+    def parse_json_array(value)
+      return nil if value.nil? || value.empty?
+
+      JSON.parse(value)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+
+  # Configuration class for Hatchet client settings
+  #
+  # This class manages all configuration options for the Hatchet client, including
+  # token authentication, connection settings, and various client behaviors.
+  # Configuration can be set via constructor options, environment variables, or
+  # extracted from JWT tokens.
+  #
+  # @example Basic configuration
+  #   config = Config.new(token: "your-jwt-token")
+  #
+  # @example Full configuration with all options
+  #   config = Config.new(
+  #     token: "your-jwt-token",
+  #     host_port: "localhost:7070",
+  #     server_url: "https://api.hatchet.com",
+  #     namespace: "production",
+  #     tenant_id: "custom-tenant",
+  #     worker_preset_labels: { "env" => "prod", "region" => "us-east-1" }
+  #   )
+  #
+  # @example Configuration via environment variables
+  #   ENV["HATCHET_CLIENT_TOKEN"] = "your-jwt-token"
+  #   ENV["HATCHET_CLIENT_HOST_PORT"] = "localhost:7070"
+  #   config = Config.new  # Will load from environment
+  class Config
+    DEFAULT_HOST_PORT = "localhost:7070"
+    DEFAULT_SERVER_URL = "https://app.dev.hatchet-tools.com"
+    DEFAULT_GRPC_MAX_MESSAGE_LENGTH = 4 * 1024 * 1024 # 4MB
+
+    ENV_FILE_NAMES = [".env", ".env.hatchet", ".env.dev", ".env.local"].freeze
+
+    # @!attribute token
+    #   @return [String] JWT token for authentication
+    # @!attribute tenant_id
+    #   @return [String] Tenant ID (extracted from JWT 'sub' field if not provided)
+    # @!attribute host_port
+    #   @return [String] gRPC server host and port
+    # @!attribute server_url
+    #   @return [String] Server URL for HTTP requests
+    # @!attribute namespace
+    #   @return [String] Namespace prefix for resource names
+    # @!attribute logger
+    #   @return [Logger] Logger instance
+    # @!attribute listener_v2_timeout
+    #   @return [Integer, nil] Timeout for listener v2 in milliseconds
+    # @!attribute grpc_max_recv_message_length
+    #   @return [Integer] Maximum gRPC receive message length in bytes
+    # @!attribute grpc_max_send_message_length
+    #   @return [Integer] Maximum gRPC send message length in bytes
+    # @!attribute worker_preset_labels
+    #   @return [Hash<String, String>] Hash of preset labels for workers
+    # @!attribute enable_force_kill_sync_threads
+    #   @return [Boolean] Enable force killing of sync threads
+    # @!attribute enable_thread_pool_monitoring
+    #   @return [Boolean] Enable thread pool monitoring
+    # @!attribute terminate_worker_after_num_tasks
+    #   @return [Integer, nil] Terminate worker after this many tasks
+    # @!attribute disable_log_capture
+    #   @return [Boolean] Disable log capture
+    # @!attribute grpc_enable_fork_support
+    #   @return [Boolean] Enable gRPC fork support
+    # @!attribute tls_config
+    #   @return [TLSConfig] TLS configuration
+    # @!attribute healthcheck
+    #   @return [HealthcheckConfig] Healthcheck configuration
+    # @!attribute otel
+    #   @return [OpenTelemetryConfig] OpenTelemetry configuration
+    attr_accessor :token, :tenant_id, :host_port, :server_url, :namespace,
+                  :logger, :listener_v2_timeout, :grpc_max_recv_message_length,
+                  :grpc_max_send_message_length, :worker_preset_labels,
+                  :enable_force_kill_sync_threads, :enable_thread_pool_monitoring,
+                  :terminate_worker_after_num_tasks, :disable_log_capture,
+                  :grpc_enable_fork_support, :tls_config, :healthcheck, :otel
+
+    # Initialize a new configuration instance
+    #
+    # Configuration values are loaded in the following priority order:
+    # 1. Explicit constructor options (highest priority)
+    # 2. Environment variables (HATCHET_CLIENT_*)
+    # 3. JWT token payload (for tenant_id from 'sub' field)
+    # 4. Default values (lowest priority)
+    #
+    # @param options [Hash] Configuration options
+    # @option options [String] :token JWT token for authentication (required)
+    # @option options [String] :tenant_id Override tenant ID (extracted from JWT 'sub' field if not provided)
+    # @option options [String] :host_port gRPC server host and port (default: "localhost:7070")
+    # @option options [String] :server_url Server URL for HTTP requests (default: "https://app.dev.hatchet-tools.com")
+    # @option options [String] :namespace Namespace prefix for resource names (default: "")
+    # @option options [Logger] :logger Custom logger instance (default: Logger.new($stdout))
+    # @option options [Integer] :listener_v2_timeout Timeout for listener v2 in milliseconds
+    # @option options [Integer] :grpc_max_recv_message_length Maximum gRPC receive message length in bytes (default: 4MB)
+    # @option options [Integer] :grpc_max_send_message_length Maximum gRPC send message length in bytes (default: 4MB)
+    # @option options [Hash<String, String>] :worker_preset_labels Hash of preset labels for workers
+    # @option options [Boolean] :enable_force_kill_sync_threads Enable force killing of sync threads (default: false)
+    # @option options [Boolean] :enable_thread_pool_monitoring Enable thread pool monitoring (default: false)
+    # @option options [Integer] :terminate_worker_after_num_tasks Terminate worker after this many tasks
+    # @option options [Boolean] :disable_log_capture Disable log capture (default: false)
+    # @option options [Boolean] :grpc_enable_fork_support Enable gRPC fork support (default: false)
+    # @option options [TLSConfig] :tls_config Custom TLS configuration
+    # @option options [HealthcheckConfig] :healthcheck Custom healthcheck configuration
+    # @option options [OpenTelemetryConfig] :otel Custom OpenTelemetry configuration
+    #
+    # @raise [Error] if token is missing, empty, or not a valid JWT
+    def initialize(**options)
+      load_env_files
+      @explicitly_set = options.keys.to_set
+
+      @token = options[:token] || env_var("HATCHET_CLIENT_TOKEN") || ""
+      @tenant_id = options[:tenant_id] || env_var("HATCHET_CLIENT_TENANT_ID") || ""
+      @host_port = options[:host_port] || env_var("HATCHET_CLIENT_HOST_PORT") || DEFAULT_HOST_PORT
+      @server_url = options[:server_url] || env_var("HATCHET_CLIENT_SERVER_URL") || DEFAULT_SERVER_URL
+      @namespace = options[:namespace] || env_var("HATCHET_CLIENT_NAMESPACE") || ""
+      @logger = options[:logger] || Logger.new($stdout)
+
+      @listener_v2_timeout = parse_int(options[:listener_v2_timeout] || env_var("HATCHET_CLIENT_LISTENER_V2_TIMEOUT"))
+      @grpc_max_recv_message_length = parse_int(
+        options[:grpc_max_recv_message_length] ||
+        env_var("HATCHET_CLIENT_GRPC_MAX_RECV_MESSAGE_LENGTH")
+      ) || DEFAULT_GRPC_MAX_MESSAGE_LENGTH
+      @grpc_max_send_message_length = parse_int(
+        options[:grpc_max_send_message_length] ||
+        env_var("HATCHET_CLIENT_GRPC_MAX_SEND_MESSAGE_LENGTH")
+      ) || DEFAULT_GRPC_MAX_MESSAGE_LENGTH
+
+      @worker_preset_labels = options[:worker_preset_labels] ||
+                              parse_hash(env_var("HATCHET_CLIENT_WORKER_PRESET_LABELS")) || {}
+      @enable_force_kill_sync_threads = parse_bool(
+        options[:enable_force_kill_sync_threads] ||
+        env_var("HATCHET_CLIENT_ENABLE_FORCE_KILL_SYNC_THREADS")
+      ) || false
+      @enable_thread_pool_monitoring = parse_bool(
+        options[:enable_thread_pool_monitoring] ||
+        env_var("HATCHET_CLIENT_ENABLE_THREAD_POOL_MONITORING")
+      ) || false
+      @terminate_worker_after_num_tasks = parse_int(
+        options[:terminate_worker_after_num_tasks] ||
+        env_var("HATCHET_CLIENT_TERMINATE_WORKER_AFTER_NUM_TASKS")
+      )
+      @disable_log_capture = parse_bool(
+        options[:disable_log_capture] ||
+        env_var("HATCHET_CLIENT_DISABLE_LOG_CAPTURE")
+      ) || false
+      @grpc_enable_fork_support = parse_bool(
+        options[:grpc_enable_fork_support] ||
+        env_var("HATCHET_CLIENT_GRPC_ENABLE_FORK_SUPPORT")
+      ) || false
+
+      # Initialize nested configurations
+      @tls_config = options[:tls_config] || TLSConfig.new
+      @healthcheck = options[:healthcheck] || HealthcheckConfig.new
+      @otel = options[:otel] || OpenTelemetryConfig.new
+
+      validate!
+      apply_token_defaults if valid_jwt_token?
+      apply_address_defaults if valid_jwt_token?
+      normalize_namespace!
+    end
+
+    def validate!
+      raise Error, "Hatchet Token is required. Please set HATCHET_CLIENT_TOKEN in your environment." if token.nil? || token.empty?
+
+      return if valid_jwt_token?
+
+      raise Error,
+            "Hatchet Token must be a valid JWT."
+    end
+
+    # Apply namespace prefix to a resource name
+    #
+    # @param resource_name [String, nil] The resource name to namespace
+    # @param namespace_override [String, nil] Optional namespace to use instead of the configured one
+    # @return [String, nil] The namespaced resource name, or nil if resource_name is nil
+    #
+    # @example Apply default namespace
+    #   config = Config.new(token: "token", namespace: "prod")
+    #   config.apply_namespace("workflow") #=> "prod_workflow"
+    #
+    # @example Apply custom namespace
+    #   config.apply_namespace("workflow", namespace_override: "staging_") #=> "staging_workflow"
+    #
+    # @example Skip namespace if already present
+    #   config.apply_namespace("prod_workflow") #=> "prod_workflow"
+    def apply_namespace(resource_name, namespace_override: nil)
+      return resource_name if resource_name.nil?
+
+      namespace_to_use = namespace_override || namespace
+      return resource_name if namespace_to_use.empty?
+      return resource_name if resource_name.start_with?(namespace_to_use)
+
+      "#{namespace_to_use}#{resource_name}"
+    end
+
+    def hash
+      to_h.hash
+    end
+
+    # Convert configuration to a hash representation
+    #
+    # @return [Hash<Symbol, Object>] Hash containing all configuration values
+    def to_h
+      {
+        token: token,
+        tenant_id: tenant_id,
+        host_port: host_port,
+        server_url: server_url,
+        namespace: namespace,
+        listener_v2_timeout: listener_v2_timeout,
+        grpc_max_recv_message_length: grpc_max_recv_message_length,
+        grpc_max_send_message_length: grpc_max_send_message_length,
+        worker_preset_labels: worker_preset_labels,
+        enable_force_kill_sync_threads: enable_force_kill_sync_threads,
+        enable_thread_pool_monitoring: enable_thread_pool_monitoring,
+        terminate_worker_after_num_tasks: terminate_worker_after_num_tasks,
+        disable_log_capture: disable_log_capture,
+        grpc_enable_fork_support: grpc_enable_fork_support
+      }
+    end
+
+    private
+
+    def valid_jwt_token?
+      !token.nil? && !token.empty? && token.start_with?("ey")
+    end
+
+    def apply_token_defaults
+      return unless tenant_id.empty?
+
+      extracted_tenant_id = extract_tenant_id_from_jwt
+      @tenant_id = extracted_tenant_id || ""
+    end
+
+    def apply_address_defaults
+      jwt_server_url, jwt_host_port = extract_addresses_from_jwt
+
+      @host_port = jwt_host_port if jwt_host_port && !explicitly_set?(:host_port)
+      @server_url = jwt_server_url if jwt_server_url && !explicitly_set?(:server_url)
+
+      # Set TLS server name if not already set
+      return unless tls_config.server_name.empty?
+
+      tls_config.server_name = host_port.split(":").first || "localhost"
+    end
+
+    def normalize_namespace!
+      return if namespace.empty?
+
+      @namespace = namespace.downcase
+      @namespace += "_" unless @namespace.end_with?("_")
+    end
+
+    def load_env_files
+      ENV_FILE_NAMES.each do |env_file|
+        next unless File.exist?(env_file)
+
+        File.foreach(env_file) do |line|
+          line = line.strip
+          next if line.empty? || line.start_with?("#")
+
+          key, value = line.split("=", 2)
+          next unless key && value
+
+          ENV[key] ||= value.gsub(/\A['"]|['"]\z/, "") # Remove surrounding quotes
+        end
+      end
+    end
+
+    def env_var(name)
+      ENV[name]
+    end
+
+    def parse_int(value)
+      return nil if value.nil?
+      return value if value.is_a?(Integer)
+      return nil if value.respond_to?(:empty?) && value.empty?
+
+      Integer(value)
+    rescue ArgumentError
+      nil
+    end
+
+    def parse_bool(value)
+      return nil if value.nil?
+      return value if [true, false].include?(value)
+
+      %w[true 1 yes on].include?(value.to_s.downcase)
+    end
+
+    def parse_hash(value)
+      return nil if value.nil? || value.empty?
+
+      # Simple key=value,key2=value2 parsing
+      result = {}
+      value.split(",").each do |pair|
+        key, val = pair.split("=", 2)
+        result[key.strip] = val&.strip if key && val
+      end
+      result
+    rescue StandardError
+      nil
+    end
+
+    def explicitly_set?(attr)
+      @explicitly_set.include?(attr)
+    end
+
+    def extract_tenant_id_from_jwt
+      return nil unless valid_jwt_token?
+
+      payload = decode_jwt_payload
+      payload&.dig("sub")
+    rescue StandardError
+      nil
+    end
+
+    def extract_addresses_from_jwt
+      return [nil, nil] unless valid_jwt_token?
+
+      payload = decode_jwt_payload
+      return [nil, nil] unless payload
+
+      server_url = payload["server_url"]
+      grpc_broadcast_address = payload["grpc_broadcast_address"]
+
+      [server_url, grpc_broadcast_address]
+    rescue StandardError
+      [nil, nil]
+    end
+
+    def decode_jwt_payload
+      return nil unless valid_jwt_token?
+
+      # JWT has three parts separated by dots: header.payload.signature
+      parts = token.split(".")
+      return nil unless parts.length == 3
+
+      # Decode the payload (second part)
+      payload_part = parts[1]
+      # Add padding if needed for Base64 decoding
+      payload_part += "=" * (4 - payload_part.length % 4) if payload_part.length % 4 != 0
+
+      decoded_payload = Base64.decode64(payload_part)
+      JSON.parse(decoded_payload)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/hatchet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hatchet
-  VERSION = "0.0.0"
+  VERSION = "0.0.1"
 end

data/lib/hatchet-sdk.rb

@@ -1,15 +1,65 @@
 # frozen_string_literal: true
+# typed: strict
 
 require_relative "hatchet/version"
+require_relative "hatchet/config"
 
+# Ruby SDK for Hatchet workflow engine
+#
+# @see https://docs.hatchet.run for Hatchet documentation
 module Hatchet
+  # Base error class for all Hatchet-related errors
   class Error < StandardError; end
 
+  # The main client for interacting with Hatchet services.
+  #
+  # @example Basic usage with API token
+  #   hatchet = Hatchet::Client.new()
+  #
+  # @example With custom configuration
+  #   hatchet = Hatchet::Client.new(
+  #     token: "your-jwt-token",
+  #     namespace: "production"
+  #   )
   class Client
-    attr_reader :api_key
+    # @return [Config] The configuration object used by this client
+    attr_reader :config
 
-    def initialize(api_key)
-      @api_key = api_key
+    # Initialize a new Hatchet client with the given configuration options.
+    #
+    # @param options [Hash] Configuration options for the client
+    # @option options [String] :token The JWT token for authentication (required)
+    # @option options [String] :tenant_id Override tenant ID (extracted from JWT token 'sub' field if not provided)
+    # @option options [String] :host_port gRPC server host and port (default: "localhost:7070")
+    # @option options [String] :server_url Server URL for HTTP requests (default: "https://app.dev.hatchet-tools.com")
+    # @option options [String] :namespace Namespace prefix for resource names (default: "")
+    # @option options [Logger] :logger Custom logger instance (default: Logger.new($stdout))
+    # @option options [Integer] :listener_v2_timeout Timeout for listener v2 in milliseconds
+    # @option options [Integer] :grpc_max_recv_message_length Maximum gRPC receive message length (default: 4MB)
+    # @option options [Integer] :grpc_max_send_message_length Maximum gRPC send message length (default: 4MB)
+    # @option options [Hash] :worker_preset_labels Hash of preset labels for workers
+    # @option options [Boolean] :enable_force_kill_sync_threads Enable force killing of sync threads (default: false)
+    # @option options [Boolean] :enable_thread_pool_monitoring Enable thread pool monitoring (default: false)
+    # @option options [Integer] :terminate_worker_after_num_tasks Terminate worker after this many tasks
+    # @option options [Boolean] :disable_log_capture Disable log capture (default: false)
+    # @option options [Boolean] :grpc_enable_fork_support Enable gRPC fork support (default: false)
+    # @option options [TLSConfig] :tls_config Custom TLS configuration
+    # @option options [HealthcheckConfig] :healthcheck Custom healthcheck configuration
+    # @option options [OpenTelemetryConfig] :otel Custom OpenTelemetry configuration
+    #
+    # @raise [Error] if token or configuration is missing or invalid
+    #
+    # @example Initialize with minimal configuration
+    #   client = Hatchet::Client.new()
+    #
+    # @example Initialize with custom options
+    #   client = Hatchet::Client.new(
+    #     token: "eyJhbGciOiJIUzI1NiJ9...",
+    #     namespace: "my_app",
+    #     worker_preset_labels: { "env" => "production", "version" => "1.0.0" }
+    #   )
+    def initialize(**options)
+      @config = Config.new(**options)
     end
   end
 end

data/sig/hatchet-sdk.rbs

@@ -1,4 +1,106 @@
 module Hatchet
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end
+
+  class Error < StandardError
+  end
+
+  class Client
+    attr_reader config: Config
+
+    def initialize: (
+      ?token: String,
+      ?tenant_id: String,
+      ?host_port: String,
+      ?server_url: String,
+      ?namespace: String,
+      ?logger: Logger,
+      ?listener_v2_timeout: Integer,
+      ?grpc_max_recv_message_length: Integer,
+      ?grpc_max_send_message_length: Integer,
+      ?worker_preset_labels: Hash[String, String],
+      ?enable_force_kill_sync_threads: bool,
+      ?enable_thread_pool_monitoring: bool,
+      ?terminate_worker_after_num_tasks: Integer,
+      ?disable_log_capture: bool,
+      ?grpc_enable_fork_support: bool,
+      ?tls_config: TLSConfig,
+      ?healthcheck: HealthcheckConfig,
+      ?otel: OpenTelemetryConfig
+    ) -> void
+  end
+
+  class Config
+    attr_accessor token: String
+    attr_accessor tenant_id: String
+    attr_accessor host_port: String
+    attr_accessor server_url: String
+    attr_accessor namespace: String
+    attr_accessor logger: Logger
+    attr_accessor listener_v2_timeout: Integer?
+    attr_accessor grpc_max_recv_message_length: Integer
+    attr_accessor grpc_max_send_message_length: Integer
+    attr_accessor worker_preset_labels: Hash[String, String]
+    attr_accessor enable_force_kill_sync_threads: bool
+    attr_accessor enable_thread_pool_monitoring: bool
+    attr_accessor terminate_worker_after_num_tasks: Integer?
+    attr_accessor disable_log_capture: bool
+    attr_accessor grpc_enable_fork_support: bool
+    attr_accessor tls_config: TLSConfig
+    attr_accessor healthcheck: HealthcheckConfig
+    attr_accessor otel: OpenTelemetryConfig
+
+    def initialize: (
+      ?token: String,
+      ?tenant_id: String,
+      ?host_port: String,
+      ?server_url: String,
+      ?namespace: String,
+      ?logger: Logger,
+      ?listener_v2_timeout: Integer,
+      ?grpc_max_recv_message_length: Integer,
+      ?grpc_max_send_message_length: Integer,
+      ?worker_preset_labels: Hash[String, String],
+      ?enable_force_kill_sync_threads: bool,
+      ?enable_thread_pool_monitoring: bool,
+      ?terminate_worker_after_num_tasks: Integer,
+      ?disable_log_capture: bool,
+      ?grpc_enable_fork_support: bool,
+      ?tls_config: TLSConfig,
+      ?healthcheck: HealthcheckConfig,
+      ?otel: OpenTelemetryConfig
+    ) -> void
+
+    def apply_namespace: (String? resource_name, ?namespace_override: String?) -> String?
+    def hash: () -> Integer
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class TLSConfig
+    attr_accessor strategy: String
+    attr_accessor cert_file: String?
+    attr_accessor key_file: String?
+    attr_accessor root_ca_file: String?
+    attr_accessor server_name: String
+
+    def initialize: (
+      ?strategy: String,
+      ?cert_file: String,
+      ?key_file: String,
+      ?root_ca_file: String,
+      ?server_name: String
+    ) -> void
+  end
+
+  class HealthcheckConfig
+    attr_accessor port: Integer
+    attr_accessor enabled: bool
+
+    def initialize: (?port: Integer, ?enabled: bool) -> void
+  end
+
+  class OpenTelemetryConfig
+    attr_accessor excluded_attributes: Array[String]
+
+    def initialize: (?excluded_attributes: Array[String]) -> void
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hatchet-sdk
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
 platform: ruby
 authors:
 - gabriel ruttner
@@ -54,6 +54,7 @@ files:
 - README.md
 - Rakefile
 - lib/hatchet-sdk.rb
+- lib/hatchet/config.rb
 - lib/hatchet/version.rb
 - sig/hatchet-sdk.rbs
 homepage: https://hatchet.run