tyler_efm_client 1.0.0.pre.alpha.1

data/README.md

@@ -0,0 +1,298 @@
+# Tyler EFM Client - Ruby SDK
+
+[![Ruby Version](https://img.shields.io/badge/ruby-2.7%2B-red.svg)](https://ruby-lang.org)
+[![Gem Version](https://badge.fury.io/rb/tyler_efm_client.svg)](https://badge.fury.io/rb/tyler_efm_client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tyler Technologies](https://img.shields.io/badge/Tyler-Technologies-blue.svg)](https://tylertech.com)
+
+A production-ready Ruby SDK for integrating with Tyler Technologies Electronic Filing Manager (EFM) services. This gem simplifies authentication and SOAP service calls for Electronic Court Filing (ECF) systems.
+
+## 🚀 Features
+
+- **Simple Authentication**: One method to authenticate with Tyler EFM services
+- **Flexible SOAP Operations**: Call any Tyler EFM SOAP operation with automatic security handling
+- **WS-Security Support**: Automatic RSA-SHA1/SHA1 digital signatures (Tyler legacy compatibility)
+- **Certificate Management**: Automatic PFX certificate handling and cleanup
+- **Response Formats**: Choose between XML and JSON response formats
+- **Production Ready**: Built from working Tyler ECF 5.0 integration code
+- **Ruby Idiomatic**: Follows Ruby conventions and best practices
+
+## 📦 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tyler_efm_client'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install tyler_efm_client
+```
+
+### Requirements
+
+- Ruby 2.7+
+- Valid Tyler EFM PFX certificate
+- Access to Tyler EFM services (staging or production)
+
+## 🔧 Quick Start
+
+### Basic Authentication
+
+```ruby
+require 'tyler_efm_client'
+
+# Initialize client
+client = TylerEfmClient::Client.new
+
+# Authenticate
+auth_result = client.authenticate(
+  base_url: "https://your-tyler-server.com/EFM/EFMUserService.svc",
+  pfx_file: "path/to/certificate.pfx",
+  pfx_password: "certificate_password",
+  user_email: "your-email@example.com",
+  user_password: "your_password"
+)
+
+if auth_result.success?
+  puts "Password Hash: #{auth_result.password_hash}"
+  puts "User: #{auth_result.first_name} #{auth_result.last_name}"
+else
+  puts "Error: #{auth_result.error_message}"
+end
+```
+
+### Service Operations
+
+```ruby
+# Call GetCaseList operation
+soap_body = <<~SOAP
+  <wrappers:GetCaseListRequest xmlns:wrappers="https://docs.oasis-open.org/legalxml-courtfiling/ns/v5.0/wrappers">
+    <!-- Your SOAP body content -->
+  </wrappers:GetCaseListRequest>
+SOAP
+
+response = client.call_service(
+  base_url: "https://your-tyler-server.com/efm/v5/CourtRecordService.svc",
+  password_hash: auth_result.password_hash,
+  operation: "GetCaseList",
+  soap_body: soap_body,
+  user_email: "your-email@example.com",
+  return_json: true  # Get JSON response instead of XML
+)
+
+if response.success?
+  puts "Service call successful!"
+  if response.json_data
+    # Work with JSON data
+    pp response.json_data
+  else
+    # Work with raw XML
+    puts response.raw_xml
+  end
+end
+```
+
+## 📚 API Reference
+
+### TylerEfmClient::Client
+
+The main client class for Tyler EFM operations.
+
+#### #authenticate(base_url:, pfx_file:, pfx_password:, user_email:, user_password:)
+
+Authenticate with Tyler EFM User Service.
+
+**Parameters:**
+- `base_url` (String): Base URL for the EFM User Service
+- `pfx_file` (String): Path to the PFX certificate file
+- `pfx_password` (String): Password for the PFX certificate  
+- `user_email` (String): User's email address
+- `user_password` (String): User's password
+
+**Returns:** `TylerEfmClient::AuthenticationResult` object with:
+- `success?` (Boolean): Whether authentication succeeded
+- `password_hash` (String): Password hash for subsequent service calls
+- `user_id` (String): User's unique identifier
+- `first_name` (String): User's first name
+- `last_name` (String): User's last name
+- `email` (String): User's email
+- `expiration_date` (String): Token expiration date
+- `error_code` (String): Error code if authentication failed
+- `error_message` (String): Error message if authentication failed
+
+#### #call_service(base_url:, password_hash:, operation:, soap_body:, **options)
+
+Call any Tyler EFM SOAP service operation.
+
+**Parameters:**
+- `base_url` (String): Base URL for the EFM service
+- `password_hash` (String): Password hash from authentication
+- `operation` (String): Name of the SOAP operation
+- `soap_body` (String): SOAP body content as XML string
+- `user_email` (String, optional): User's email (required for Court Record Service)
+- `pfx_file` (String, optional): Path to PFX certificate if not from authentication
+- `pfx_password` (String, optional): PFX password if not from authentication
+- `return_json` (Boolean, optional): Return JSON instead of XML (default: false)
+- `soap_action` (String, optional): Custom SOAP action header
+
+**Returns:** `TylerEfmClient::ServiceResponse` object with:
+- `success?` (Boolean): Whether the service call succeeded
+- `status_code` (Integer): HTTP status code
+- `raw_xml` (String): Raw XML response
+- `json_data` (Hash, optional): JSON representation of response if requested
+- `error_message` (String, optional): Error message if call failed
+
+## 🏗️ Architecture
+
+This SDK implements Tyler's exact ECF 5.0 requirements:
+
+### Authentication (User Service)
+- **WS-Security**: Digital signatures using RSA-SHA1/SHA1 (Tyler legacy requirement)
+- **Certificate Auth**: Mutual TLS using PFX certificates
+- **SOAP Structure**: Exact Tyler-compatible XML namespace handling
+
+### Court Record Service Operations
+- **UserNameHeader**: Special header structure required by Court Record Service
+- **No Namespace Prefix**: Critical requirement - UserNameHeader must not have namespace prefix
+- **Header Order**: UserNameHeader must be first header element
+- **Password Hash**: Uses hashed password from authentication, not plain password
+
+## 🔒 Security Features
+
+- **Automatic Certificate Handling**: PFX files are processed and cleaned up automatically
+- **WS-Security Signatures**: RSA-SHA1 digital signatures for message integrity
+- **Legacy Algorithm Support**: SHA1 and RSA-SHA1 for Tyler compatibility
+- **HTTPS Only**: All communications use HTTPS with certificate verification
+
+## 📖 Examples
+
+The `examples/` directory contains complete working examples:
+
+- `authentication_example.rb` - Basic authentication
+- `getcaselist_example.rb` - GetCaseList operation
+- `complete_workflow_example.rb` - Full workflow with multiple operations
+
+Run examples:
+
+```bash
+cd examples
+ruby authentication_example.rb
+ruby getcaselist_example.rb
+ruby complete_workflow_example.rb
+```
+
+## 🐛 Error Handling
+
+The SDK provides specific exception types:
+
+```ruby
+begin
+  auth_result = client.authenticate(...)
+rescue TylerEfmClient::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue TylerEfmClient::CertificateError => e
+  puts "Certificate error: #{e.message}"
+rescue TylerEfmClient::ServiceError => e
+  puts "Service error: #{e.message}"
+rescue TylerEfmClient::Error => e
+  puts "EFM client error: #{e.message}"
+end
+```
+
+## 🧪 Testing
+
+The SDK is built from working Tyler ECF integration code and tested against:
+
+- Tyler Georgia staging environment
+- Production Tyler ECF 5.0 systems
+- Multiple certificate types and configurations
+
+Run tests:
+
+```bash
+bundle exec rake spec
+```
+
+Run linting:
+
+```bash
+bundle exec rake rubocop
+```
+
+## 📋 Requirements
+
+### System Requirements
+- Ruby 2.7 or higher
+- OpenSSL for certificate processing
+- Network access to Tyler EFM services
+
+### Tyler Requirements
+- Valid Tyler EFM account and credentials
+- PFX certificate file from Tyler Technologies
+- Appropriate service URLs (staging or production)
+
+## 🔧 Development
+
+After checking out the repo, run:
+
+```bash
+bin/setup
+```
+
+To install dependencies. Then, run:
+
+```bash
+rake spec
+```
+
+To run the tests. You can also run:
+
+```bash
+bin/console
+```
+
+For an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run:
+
+```bash
+bundle exec rake install
+```
+
+To release a new version:
+
+1. Update the version number in `lib/tyler_efm_client/version.rb`
+2. Run `bundle exec rake release`
+
+This will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/tyler-technologies/cj-esol-efm-client-ruby.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## 📄 License
+
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 🏢 About Tyler Technologies
+
+Tyler Technologies is a leading provider of integrated software and technology services to the public sector. Learn more at [tylertech.com](https://www.tylertech.com).
+
+---
+
+**Built with ❤️ for the Tyler ECF community**

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new do |task|
+  task.requires << 'rubocop-performance'
+end
+
+task default: %i[spec rubocop]

data/build_gem.rb

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'fileutils'
+
+##
+# Build script for Tyler EFM Client Ruby gem
+def run_command(command, description)
+  puts "🔄 #{description}..."
+  result = system(command)
+  if result
+    puts "✅ #{description} completed"
+    true
+  else
+    puts "❌ #{description} failed"
+    false
+  end
+end
+
+def clean_build
+  puts '🧹 Cleaning build artifacts...'
+  
+  files_to_clean = ['*.gem', 'Gemfile.lock']
+  files_to_clean.each do |pattern|
+    Dir.glob(pattern).each do |file|
+      File.delete(file)
+      puts "   Removed: #{file}"
+    end
+  end
+  
+  puts '✅ Build artifacts cleaned'
+end
+
+def build_gem
+  puts 'Tyler EFM Client - Ruby Gem Build Script'
+  puts '=' * 45
+  
+  # Clean previous builds
+  clean_build
+  
+  # Install dependencies
+  unless run_command('bundle install', 'Installing dependencies')
+    return false
+  end
+  
+  # Build the gem
+  unless run_command('gem build tyler_efm_client.gemspec', 'Building gem')
+    return false
+  end
+  
+  # List built gems
+  puts "\n🎉 Gem built successfully!"
+  puts '📦 Distribution files:'
+  
+  Dir.glob('*.gem').each do |gem_file|
+    size = File.size(gem_file)
+    puts "   #{gem_file} (#{size} bytes)"
+  end
+  
+  puts "\n📋 Next steps:"
+  puts '   1. Test the built gem:'
+  puts '      gem install tyler_efm_client-1.0.0.gem'
+  puts '   2. Push to RubyGems (test):'
+  puts '      gem push --host https://test.rubygems.org tyler_efm_client-1.0.0.gem'
+  puts '   3. Push to RubyGems (production):'
+  puts '      gem push tyler_efm_client-1.0.0.gem'
+  puts '   4. Run tests:'
+  puts '      bundle exec rake spec'
+  
+  true
+end
+
+exit(build_gem ? 0 : 1) if __FILE__ == $0

data/config.example.json

@@ -0,0 +1,15 @@
+{
+  "service": {
+    "endpoint": "https://georgia-stage.tylertech.cloud/EFM/EFMUserService.svc",
+    "wsdl_url": "https://georgia-stage.tylertech.cloud/EFM/EFMUserService.svc?wsdl",
+    "court_service_url": "https://georgia-stage.tylertech.cloud/efm/v5/CourtRecordService.svc"
+  },
+  "certificate": {
+    "pfx_file": "YOUR_CERTIFICATE.pfx",
+    "pfx_password": "YOUR_PFX_PASSWORD"
+  },
+  "credentials": {
+    "email": "your-email@domain.com",
+    "password": "your-password"
+  }
+}

data/docs/getting_started.md

@@ -0,0 +1,293 @@
+# Getting Started with Tyler EFM Client - Ruby SDK
+
+Welcome to the Tyler EFM Client Ruby SDK! This guide will help you get up and running with Tyler Technologies Electronic Filing Manager (EFM) services quickly.
+
+## 📋 Prerequisites
+
+Before you begin, ensure you have:
+
+1. **Ruby Environment**: Ruby 2.7 or higher
+2. **Tyler EFM Account**: Valid credentials from Tyler Technologies
+3. **PFX Certificate**: Client certificate file from Tyler Technologies
+4. **Service Access**: URLs for Tyler EFM services (staging or production)
+
+## 🚀 Installation
+
+### Using Bundler (Recommended)
+
+Add to your Gemfile:
+```ruby
+gem 'tyler_efm_client'
+```
+
+Then run:
+```bash
+bundle install
+```
+
+### Direct Installation
+
+```bash
+gem install tyler_efm_client
+```
+
+## 🔧 Basic Setup
+
+### 1. Require the Gem
+
+```ruby
+require 'tyler_efm_client'
+```
+
+### 2. Initialize the Client
+
+```ruby
+client = TylerEfmClient::Client.new
+```
+
+### 3. Authenticate
+
+```ruby
+auth_result = client.authenticate(
+  base_url: "https://georgia-stage.tylertech.cloud/EFM/EFMUserService.svc",
+  pfx_file: "path/to/your/certificate.pfx",
+  pfx_password: "your_certificate_password",
+  user_email: "your-email@example.com",
+  user_password: "your_password"
+)
+
+if auth_result.success?
+  puts "✅ Authentication successful!"
+  puts "Password Hash: #{auth_result.password_hash}"
+  puts "User: #{auth_result.first_name} #{auth_result.last_name}"
+else
+  puts "❌ Authentication failed: #{auth_result.error_message}"
+end
+```
+
+## 🎯 Your First Service Call
+
+Once authenticated, you can call any Tyler EFM service:
+
+```ruby
+# Example: GetCaseList operation
+soap_body = <<~SOAP
+  <wrappers:GetCaseListRequest xmlns:wrappers="https://docs.oasis-open.org/legalxml-courtfiling/ns/v5.0/wrappers">
+    <wrappers:GetCaseListRequestMessage>
+      <nc:Case xmlns:nc="http://niem.gov/niem/niem-core/2.0">
+        <nc:CaseTitleText>*</nc:CaseTitleText>
+      </nc:Case>
+    </wrappers:GetCaseListRequestMessage>
+  </wrappers:GetCaseListRequest>
+SOAP
+
+response = client.call_service(
+  base_url: "https://georgia-stage.tylertech.cloud/efm/v5/CourtRecordService.svc",
+  password_hash: auth_result.password_hash,
+  operation: "GetCaseList",
+  soap_body: soap_body,
+  user_email: "your-email@example.com",
+  return_json: true  # Get JSON instead of XML
+)
+
+if response.success?
+  puts "✅ Service call successful!"
+  if response.json_data
+    puts "Cases found: #{response.json_data['cases']&.length || 0}"
+  else
+    puts "Raw XML response: #{response.raw_xml}"
+  end
+else
+  puts "❌ Service call failed: #{response.error_message}"
+end
+```
+
+## 🔒 Configuration Best Practices
+
+### Environment Variables
+
+Store sensitive information in environment variables:
+
+```ruby
+require 'tyler_efm_client'
+
+client = TylerEfmClient::Client.new
+
+auth_result = client.authenticate(
+  base_url: ENV['TYLER_EFM_BASE_URL'],
+  pfx_file: ENV['TYLER_EFM_CERT_FILE'],
+  pfx_password: ENV['TYLER_EFM_CERT_PASSWORD'],
+  user_email: ENV['TYLER_EFM_USER_EMAIL'],
+  user_password: ENV['TYLER_EFM_USER_PASSWORD']
+)
+```
+
+### Configuration Class
+
+Create a configuration class for better organization:
+
+```ruby
+class TylerConfig
+  ENVIRONMENTS = {
+    staging: {
+      user_service: "https://georgia-stage.tylertech.cloud/EFM/EFMUserService.svc",
+      court_service: "https://georgia-stage.tylertech.cloud/efm/v5/CourtRecordService.svc"
+    },
+    production: {
+      user_service: "https://georgia-prod.tylertech.cloud/EFM/EFMUserService.svc",
+      court_service: "https://georgia-prod.tylertech.cloud/efm/v5/CourtRecordService.svc"
+    }
+  }.freeze
+
+  def self.get_urls(environment = :staging)
+    ENVIRONMENTS[environment]
+  end
+end
+```
+
+## 🐛 Error Handling
+
+Always implement proper error handling:
+
+```ruby
+require 'tyler_efm_client'
+
+client = TylerEfmClient::Client.new
+
+begin
+  auth_result = client.authenticate(
+    base_url: "https://your-tyler-server.com/EFM/EFMUserService.svc",
+    pfx_file: "certificate.pfx",
+    pfx_password: "password",
+    user_email: "user@example.com",
+    user_password: "password"
+  )
+  
+  unless auth_result.success?
+    puts "Authentication failed: #{auth_result.error_message}"
+    exit(1)
+  end
+  
+rescue TylerEfmClient::AuthenticationError => e
+  puts "Authentication error: #{e.message}"
+rescue TylerEfmClient::CertificateError => e
+  puts "Certificate error: #{e.message}"
+rescue TylerEfmClient::Error => e
+  puts "EFM service error: #{e.message}"
+rescue StandardError => e
+  puts "Unexpected error: #{e.message}"
+end
+```
+
+## 📖 Ruby-Specific Features
+
+### Blocks and Yield
+
+```ruby
+def with_tyler_client(config)
+  client = TylerEfmClient::Client.new
+  
+  auth_result = client.authenticate(**config)
+  
+  if auth_result.success?
+    yield client, auth_result.password_hash
+  else
+    raise TylerEfmClient::AuthenticationError, auth_result.error_message
+  end
+end
+
+# Usage
+config = {
+  base_url: "https://georgia-stage.tylertech.cloud/EFM/EFMUserService.svc",
+  pfx_file: "cert.pfx",
+  pfx_password: "password",
+  user_email: "user@example.com",
+  user_password: "password"
+}
+
+with_tyler_client(config) do |client, password_hash|
+  response = client.call_service(
+    base_url: "https://georgia-stage.tylertech.cloud/efm/v5/CourtRecordService.svc",
+    password_hash: password_hash,
+    operation: "GetCaseList",
+    soap_body: soap_body,
+    user_email: "user@example.com"
+  )
+  
+  puts "Response received: #{response.success?}"
+end
+```
+
+### Hash-Based Configuration
+
+```ruby
+class TylerEfmWrapper
+  def initialize(config = {})
+    @config = config
+    @client = TylerEfmClient::Client.new
+    @password_hash = nil
+  end
+  
+  def authenticate
+    auth_result = @client.authenticate(**@config)
+    
+    if auth_result.success?
+      @password_hash = auth_result.password_hash
+      auth_result
+    else
+      raise TylerEfmClient::AuthenticationError, auth_result.error_message
+    end
+  end
+  
+  def call_court_service(operation, soap_body)
+    raise "Must authenticate first" unless @password_hash
+    
+    @client.call_service(
+      base_url: @config[:court_service_url],
+      password_hash: @password_hash,
+      operation: operation,
+      soap_body: soap_body,
+      user_email: @config[:user_email],
+      return_json: true
+    )
+  end
+end
+```
+
+## 📋 Next Steps
+
+Now that you have the basics working:
+
+1. **Explore Examples**: Check the `examples/` directory for complete working examples
+2. **Review Samples**: Look at `samples/` for real-world integration patterns
+3. **Read API Reference**: See `docs/api_reference.md` for detailed method documentation
+4. **Check Troubleshooting**: Review `docs/troubleshooting.md` for common issues
+
+## 🔗 Quick Links
+
+- [Authentication Guide](authentication_guide.md) - Detailed authentication setup
+- [API Reference](api_reference.md) - Complete method documentation
+- [Tyler ECF Requirements](tyler_ecf_requirements.md) - Understanding Tyler's system
+- [Troubleshooting](troubleshooting.md) - Common issues and solutions
+
+## 💎 Ruby Conventions
+
+This SDK follows Ruby conventions:
+- Method names use `snake_case`
+- Classes use `PascalCase`
+- Modules use `::` namespace separation
+- Boolean methods end with `?`
+- Destructive methods end with `!`
+
+## 📞 Support
+
+If you encounter issues:
+
+1. Check the troubleshooting guide
+2. Review your certificate and credentials
+3. Verify service URLs are correct
+4. Check Tyler ECF 5.0 documentation
+
+---
+
+**Ready to integrate with Tyler EFM using Ruby? Let's build something amazing!** 💎