hatchet-sdk 0.0.0 → 0.1.0.pre.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04cba5845adc6fdaa4fe8211dcf3326ff8e029d458ea80db7c9aa8018092a466
-  data.tar.gz: 54e7411d0da2caba1198049225642b1242fe25838d62d1b70560fefdd9bc30f5
+  metadata.gz: 39266ae76d015db9cfae9ab50c45b45772a71a6e83196a8f50d696427df1188f
+  data.tar.gz: '0989914579fb062642a4ffb31242632a0bfc5fd4bc510fbfac1c8b91a256de74'
 SHA512:
-  metadata.gz: cd5c9791787389f7a844f2cb61f9394b31ee8212a8fde4a06701be212683536de20cf78fa5db8c55a8ab03fcab09c190101ef6dd084720a92b66f739d0f2016d
-  data.tar.gz: 86d51a2da75ccd5cdae6c9fd01fb6e18e8956227661f34cd892ad26b517e51ce4add58b93fd212eec92da7621a7c4aa729746ebe39804d79dd8d5ed278f0c62c
+  metadata.gz: 610bc9c45ce11f4615d9858e66348c4fcae1f0af0f85be8763d6e5b43d6eba26b2ad3af7b521b6b058357b39cd4e386c9c13f3046043f0d056dcf86d52232387
+  data.tar.gz: 53f3136c6ff7f902df3e71b8626391ef02294c21d0333f24c6de2ae924e2d12a04754340b2b9b8f9b3d3046bc5fe438e917b8799b79e849259023d3b0cf2d14e

data/CHANGELOG.md

@@ -1,5 +1,6 @@
-## [Unreleased]
+## Hatchet SDK Changelog
 
-## [0.1.0] - 2025-08-04
+## [0.1.0] - 2025-08-05
 
 - Initial release
+- Events and Runs Rest Clients

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,73 @@ 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
+
+**REST API Generation:**
+- `rake api:generate` - Generate REST API client from OpenAPI specification
+- `rake api:clean` - Remove generated REST API client files  
+- `rake api:regenerate` - Clean and regenerate REST API client
+- `rake api:validate` - Validate OpenAPI specification
+- `rake api:info` - Show OpenAPI specification information
+- `./scripts/generate.sh` - Alternative shell script for generation
+
 ## 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
+- `lib/hatchet/clients.rb` - Client factory and REST client integration
+- `lib/hatchet/clients/rest/` - Generated REST API client (created via `rake api:generate`)
+- `spec/` - RSpec tests with monkey patching disabled (36+ test cases)
+- `sig/hatchet-sdk.rbs` - Ruby type signatures for IDE integration
+- `scripts/` - Code generation and maintenance scripts
 
 **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::Clients` - Factory for creating REST and other protocol clients
+- `Hatchet::Clients::Rest::*` - Generated REST API clients (WorkflowApi, EventApi, etc.)
+- `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
+
+**REST API Client Generation:**
+- The SDK can generate a complete REST API client from the OpenAPI spec at `../../../../bin/oas/openapi.yaml`
+- Use `rake api:generate` to create Ruby bindings for all Hatchet REST endpoints
+- Generated client integrates with `Hatchet::Config` for authentication and configuration
+- Supports both sync and async operations with comprehensive error handling
+- See `REST_API_GENERATION.md` for detailed instructions
+
+**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/INTEGRATION_TESTING.md

@@ -0,0 +1,176 @@
+# Integration Testing Guide
+
+This guide explains how to run integration tests for the Hatchet Ruby SDK that make actual API calls to test the real functionality.
+
+## Overview
+
+The Ruby SDK includes two types of tests:
+
+1. **Unit Tests** (`spec/hatchet/`) - Fast tests that use mocks and don't require API credentials
+2. **Integration Tests** (`spec/integration/`) - Tests that make real API calls and require valid credentials
+
+## Running Unit Tests
+
+Unit tests run by default and don't require any setup:
+
+```bash
+bundle exec rspec
+```
+
+## Running Integration Tests
+
+Integration tests require a valid Hatchet API token and will be skipped automatically if no credentials are found.
+
+### Prerequisites
+
+1. Valid Hatchet API token (JWT)
+2. Access to a Hatchet tenant with some workflow/task run data
+
+### Setup
+
+Set your API credentials as environment variables:
+
+```bash
+export HATCHET_CLIENT_TOKEN="your-jwt-token-here"
+```
+
+### Running Integration Tests
+
+#### Run only integration tests:
+```bash
+bundle exec rspec spec/integration/ --tag integration
+```
+
+#### Run all tests including integration:
+```bash
+bundle exec rspec
+```
+
+#### Force integration tests even without token (will skip individual tests):
+```bash
+RUN_INTEGRATION_TESTS=true bundle exec rspec spec/integration/
+```
+
+### What Integration Tests Cover
+
+The integration tests for the Runs feature test:
+
+#### ✅ Basic API Connectivity
+- List workflow runs
+- List with pagination
+- Filter operations
+- Empty result handling
+
+#### ✅ Workflow Run Operations
+- Get workflow run details
+- Get workflow run status  
+- Get workflow run results
+- Data structure validation
+
+#### ✅ Task Run Operations
+- Get task run details
+- Data structure validation
+
+#### ✅ Workflow Creation (Conditional)
+- Attempt to create workflow runs
+- Gracefully handles missing test workflows
+
+#### ✅ Error Handling
+- Invalid IDs
+- Invalid date ranges
+- Network errors
+
+#### ✅ Data Structure Validation
+- Response object structure
+- Required fields
+- Data types
+
+#### ⚠️ Bulk Operations (Structure Only)
+- Tests helper classes
+- Does NOT test actual bulk cancel/replay (too dangerous for integration tests)
+
+## Sample Output
+
+### With Valid Credentials
+```
+🔗 Running integration tests with real API credentials
+   Tenant ID: abc123-def456
+   Server URL: https://app.dev.hatchet-tools.com
+
+Hatchet::Features::Runs Integration
+  API connectivity and basic operations
+    ✓ can list workflow runs without error
+    ✓ returns a TaskSummaryList when listing runs
+    ✓ can list runs with pagination without error
+    ✓ returns an array when using list_with_pagination
+    ✓ can filter runs by various parameters
+    ✓ handles empty results gracefully
+  workflow run operations
+    ✓ can retrieve workflow run details
+    ✓ returns WorkflowRunDetails when getting a workflow run
+    ✓ can get workflow run status
+    ✓ returns a TaskStatus when getting status
+    ✓ can get workflow run result
+  ...
+```
+
+### Without Credentials
+```
+⚠️  Integration tests skipped (no HATCHET_CLIENT_TOKEN found)
+   Set HATCHET_CLIENT_TOKEN or RUN_INTEGRATION_TESTS=true to run integration tests
+
+Finished in 0.00123 seconds
+0 examples, 0 failures (all integration tests skipped)
+```
+
+## Safety Considerations
+
+The integration tests are designed to be safe:
+
+- ✅ **Read Operations**: Tests safely read existing data
+- ✅ **Safe Creation**: May attempt to create test workflows but handles failures gracefully
+- ❌ **No Destructive Operations**: Does not actually cancel or replay runs in integration tests
+- ❌ **No Data Modification**: Does not modify or delete existing workflow runs
+
+## Troubleshooting
+
+### "No recent workflow runs found for testing"
+- Your tenant needs some historical workflow runs to test against
+- Try running some workflows first, or use a tenant with existing data
+
+### "Integration tests require HATCHET_CLIENT_TOKEN to be set"
+- Make sure your JWT token is properly set in the environment
+- Verify the token is valid and not expired
+
+### API Connection Errors
+- Check your network connection
+- Verify `HATCHET_CLIENT_SERVER_URL` is correct
+- Ensure your token has the necessary permissions
+
+### Workflow Creation Failures
+- This is expected if you don't have a workflow named "test-workflow"
+- The test will show a warning but won't fail
+- Create a simple test workflow if you want to test the full creation flow
+
+## Contributing
+
+When adding new integration tests:
+
+1. Always tag them with `:integration`
+2. Use the `IntegrationHelper` methods
+3. Handle missing test data gracefully with `skip` or `safely_attempt_operation`
+4. Avoid destructive operations
+5. Validate response data structures
+6. Add appropriate documentation
+
+## CI/CD Integration
+
+For automated testing pipelines:
+
+```bash
+# Run only unit tests (fast, no credentials needed)
+bundle exec rspec --tag ~integration
+
+# Run integration tests with credentials (slower, requires setup)
+HATCHET_CLIENT_TOKEN=$SECRET_TOKEN bundle exec rspec --tag integration
+```

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 gabriel ruttner
+Copyright (c) 2025 Hatchet Technologies, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/REST_API_GENERATION.md

@@ -0,0 +1,257 @@
+# REST API Generation for Hatchet Ruby SDK
+
+This document explains how to generate and use the REST API client for the Hatchet Ruby SDK from the OpenAPI specification.
+
+## Overview
+
+The Hatchet Ruby SDK can generate a comprehensive REST API client from the OpenAPI specification located at `../../../../bin/oas/openapi.yaml`. This provides Ruby bindings for all Hatchet REST API endpoints with full type safety and documentation.
+
+## Prerequisites
+
+1. **Node.js and npm** - Required for OpenAPI Generator CLI
+2. **Ruby 3.1+** - For running the generation scripts
+3. **Bundler** - For dependency management
+
+## Quick Start
+
+### 1. Install OpenAPI Generator CLI
+
+```bash
+npm install -g @openapitools/openapi-generator-cli@latest
+```
+
+### 2. Generate the REST API Client
+
+```bash
+# Using Rake (recommended)
+rake api:generate
+
+# Or using the shell script directly
+./scripts/generate.sh
+
+# Or using the Ruby script
+ruby scripts/generate_api.rb
+```
+
+### 3. Use the Generated Client
+
+```ruby
+require 'hatchet-sdk'
+
+# Create main Hatchet configuration
+config = Hatchet::Config.new(token: "your-jwt-token")
+
+# Create REST API client
+rest_client = Hatchet::Clients.rest_client(config)
+
+# Use specific API endpoints
+workflows_api = Hatchet::Clients::Rest::WorkflowApi.new(rest_client)
+events_api = Hatchet::Clients::Rest::EventApi.new(rest_client)
+
+# Make API calls
+workflows = workflows_api.list_workflows
+```
+
+## Available Rake Tasks
+
+- `rake api:generate` - Generate REST API client from OpenAPI spec
+- `rake api:clean` - Remove generated REST API client files
+- `rake api:regenerate` - Clean and regenerate (clean + generate)
+- `rake api:validate` - Validate the OpenAPI specification
+- `rake api:install_generator` - Install OpenAPI Generator CLI if not present
+- `rake api:info` - Show information about the OpenAPI specification
+
+## Generated Structure
+
+After generation, you'll have:
+
+```
+lib/hatchet/clients/rest/
+├── api_client.rb           # Main API client
+├── configuration.rb        # Client configuration
+├── api_error.rb           # Error handling
+├── api/                   # API endpoint classes
+│   ├── workflow_api.rb    # Workflow operations
+│   ├── event_api.rb       # Event operations
+│   ├── step_run_api.rb    # Step run operations
+│   └── ... (other APIs)
+└── models/                # Data models
+    ├── workflow.rb        # Workflow model
+    ├── event.rb           # Event model
+    └── ... (other models)
+```
+
+## Configuration
+
+### OpenAPI Generator Configuration
+
+The generation is controlled by `config/openapi_generator_config.json`:
+
+```json
+{
+  "gemName": "hatchet-sdk-rest",
+  "moduleName": "Hatchet::Clients::Rest",
+  "library": "faraday",
+  "httpLibrary": "faraday",
+  "useAutoload": true,
+  "sortParamsByRequiredFlag": true,
+  "generateExceptionClass": true
+}
+```
+
+### Custom Patches
+
+The generation process applies custom patches via `scripts/patch_generated_code.rb`:
+
+1. **Module Structure** - Ensures proper Ruby module nesting
+2. **Require Statements** - Fixes require paths for gem structure
+3. **Documentation** - Adds comprehensive YARD documentation
+4. **Error Handling** - Integrates with `Hatchet::Error`
+5. **Configuration Integration** - Connects with `Hatchet::Config`
+6. **Sorbet Types** - Adds type signatures for better IDE support
+
+## Integration with Main SDK
+
+The REST client integrates seamlessly with the main SDK:
+
+```ruby
+# Main configuration
+hatchet_config = Hatchet::Config.new(
+  token: "your-jwt-token",
+  server_url: "https://api.hatchet.com"
+)
+
+# REST client automatically inherits configuration
+rest_client = Hatchet::Clients.rest_client(hatchet_config)
+
+# All configuration options are passed through:
+# - Authentication token
+# - Server URL
+# - Timeouts
+# - Custom headers
+```
+
+## Error Handling
+
+Generated API errors inherit from `Hatchet::Error`:
+
+```ruby
+begin
+  workflows = workflows_api.list_workflows
+rescue Hatchet::Clients::Rest::ApiError => e
+  puts "API Error: #{e.message}"
+  puts "Status: #{e.code}"
+  puts "Headers: #{e.response_headers}"
+  puts "Body: #{e.response_body}"
+end
+```
+
+## Type Safety and IDE Support
+
+The generated client includes:
+
+- **YARD documentation** - Comprehensive method and parameter documentation
+- **RBS type signatures** - For IDE parameter hints and type checking
+- **Sorbet compatibility** - Type annotations for static analysis
+- **Parameter validation** - Runtime validation of required parameters
+
+## Customization
+
+### Adding Custom Methods
+
+You can extend the generated API classes:
+
+```ruby
+module Hatchet
+  module Clients
+    module Rest
+      class WorkflowApi
+        # Add custom convenience methods
+        def get_workflow_by_name(name)
+          workflows = list_workflows
+          workflows.find { |w| w.name == name }
+        end
+      end
+    end
+  end
+end
+```
+
+### Custom Configuration
+
+Create specialized configurations:
+
+```ruby
+# Custom REST configuration
+rest_config = Hatchet::Clients::Rest::Configuration.new
+rest_config.access_token = "custom-token"
+rest_config.host = "custom-host.com"
+rest_config.timeout = 30
+
+rest_client = Hatchet::Clients::Rest::ApiClient.new(rest_config)
+```
+
+## Development and Debugging
+
+### Debugging Generation
+
+Set the `DEBUG` environment variable for verbose output:
+
+```bash
+DEBUG=1 rake api:generate
+```
+
+### Validation
+
+Always validate the OpenAPI spec before generation:
+
+```bash
+rake api:validate
+```
+
+### Regeneration
+
+When the OpenAPI spec changes, regenerate the client:
+
+```bash
+rake api:regenerate
+```
+
+This will clean existing files and generate fresh ones.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **OpenAPI Generator CLI not found**
+   ```bash
+   rake api:install_generator
+   ```
+
+2. **Module loading errors**
+   - Ensure you've run `bundle install` after generation
+   - Check that all required gems are installed
+
+3. **Authentication failures**
+   - Verify your JWT token is valid
+   - Check server URL configuration
+
+4. **Type errors with Sorbet**
+   - Run `bundle exec srb tc` to check types
+   - Update RBS signatures if needed
+
+### Getting Help
+
+- Check `rake api:info` for OpenAPI spec information
+- Review generated documentation in the `api/` and `models/` directories
+- Consult the main Hatchet API documentation at https://docs.hatchet.run
+
+## Maintenance
+
+The REST API generation setup requires minimal maintenance:
+
+1. **OpenAPI Spec Updates** - Regenerate when the spec changes
+2. **Dependency Updates** - Keep OpenAPI Generator CLI updated
+3. **Custom Patches** - Update patches when generation patterns change
+
+The generation process is designed to be idempotent and safe to run multiple times.

data/Rakefile

@@ -9,4 +9,13 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
+# Load REST API generation tasks
+load File.expand_path("Rakefile.rest", __dir__)
+
+# Generate REST API client before building the gem
+task :build => "api:generate"
+
+# Generate REST API client before running tests (for CI)
+task :spec => "api:generate_if_missing"
+
 task default: %i[spec rubocop]

data/Rakefile.rest

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+# Additional Rake tasks for REST API client generation
+
+require "rake"
+
+namespace :api do
+  desc "Generate REST API client from OpenAPI specification"
+  task :generate do
+    puts "Generating REST API client from OpenAPI specification..."
+    
+    ruby_script = File.join(__dir__, "scripts", "generate_api.rb")
+    
+    unless File.exist?(ruby_script)
+      puts "❌ Generator script not found at #{ruby_script}"
+      exit 1
+    end
+    
+    # Make the script executable
+    File.chmod(0755, ruby_script)
+    
+    # Execute the generation script
+    system("ruby #{ruby_script}") || begin
+      puts "❌ API generation failed"
+      exit 1
+    end
+    
+    puts "✅ REST API client generation completed"
+  end
+
+  desc "Clean generated REST API client files"
+  task :clean do
+    rest_client_dir = File.join(__dir__, "lib", "hatchet", "clients", "rest")
+    
+    if Dir.exist?(rest_client_dir)
+      puts "🧹 Cleaning generated REST API client files..."
+      require "fileutils"
+      FileUtils.rm_rf(rest_client_dir)
+      puts "✅ REST API client files cleaned"
+    else
+      puts "ℹ️  No REST API client files to clean"
+    end
+  end
+
+  desc "Regenerate REST API client (clean + generate)"
+  task regenerate: [:clean, :generate]
+
+  desc "Generate REST API client only if not already present"
+  task :generate_if_missing do
+    rest_client_dir = File.join(__dir__, "lib", "hatchet", "clients", "rest")
+    main_client_file = File.join(rest_client_dir, "lib", "hatchet-sdk-rest.rb")
+    
+    unless File.exist?(main_client_file)
+      puts "🔄 REST API client not found, generating..."
+      Rake::Task["api:generate"].invoke
+    else
+      puts "✅ REST API client already exists, skipping generation"
+    end
+  end
+
+  desc "Validate OpenAPI specification"
+  task :validate do
+    openapi_spec = File.join(__dir__, "..", "..", "..", "bin", "oas", "openapi.yaml")
+    
+    unless File.exist?(openapi_spec)
+      puts "❌ OpenAPI specification not found at #{openapi_spec}"
+      exit 1
+    end
+    
+    puts "🔍 Validating OpenAPI specification..."
+    
+    # Use openapi-generator-cli to validate the spec
+    cmd = ["openapi-generator-cli", "validate", "-i", openapi_spec]
+    
+    if system(*cmd)
+      puts "✅ OpenAPI specification is valid"
+    else
+      puts "❌ OpenAPI specification validation failed"
+      exit 1
+    end
+  end
+
+  desc "Install OpenAPI Generator CLI if not present"
+  task :install_generator do
+    puts "🔧 Checking OpenAPI Generator CLI installation..."
+    
+    if system("which openapi-generator-cli > /dev/null 2>&1")
+      puts "✅ OpenAPI Generator CLI is already installed"
+    else
+      puts "📦 Installing OpenAPI Generator CLI..."
+      
+      if system("npm install -g @openapitools/openapi-generator-cli@7.13.0")
+        puts "✅ OpenAPI Generator CLI installed successfully"
+      else
+        puts "❌ Failed to install OpenAPI Generator CLI"
+        puts "Please install it manually: npm install -g @openapitools/openapi-generator-cli"
+        exit 1
+      end
+    end
+  end
+
+  desc "Show information about the OpenAPI specification"
+  task :info do
+    openapi_spec = File.join(__dir__, "..", "..", "..", "bin", "oas", "openapi.yaml")
+    
+    unless File.exist?(openapi_spec)
+      puts "❌ OpenAPI specification not found at #{openapi_spec}"
+      exit 1
+    end
+    
+    puts "📊 OpenAPI Specification Information:"
+    puts "  File: #{openapi_spec}"
+    puts "  Size: #{File.size(openapi_spec)} bytes"
+    puts "  Modified: #{File.mtime(openapi_spec)}"
+    
+    # Try to parse and show basic info
+    begin
+      require "yaml"
+      spec = YAML.load_file(openapi_spec)
+      
+      puts "  OpenAPI Version: #{spec.dig('openapi')}"
+      puts "  API Version: #{spec.dig('info', 'version')}"
+      puts "  API Title: #{spec.dig('info', 'title')}"
+      puts "  Paths: #{spec.dig('paths')&.keys&.count || 0}"
+      puts "  Components: #{spec.dig('components', 'schemas')&.keys&.count || 0} schemas"
+    rescue => e
+      puts "  ⚠️  Could not parse specification: #{e.message}"
+    end
+  end
+end
+
+# Add REST API tasks to the default rake task
+task default: ["api:validate"]