ee_e_business_register 0.3.0

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/ee_e_business_register/client.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require 'savon'
+require 'logger'
+
+module EeEBusinessRegister
+  # SOAP client for the Estonian e-Business Register API
+  #
+  # This class handles all low-level communication with the Estonian e-Business Register
+  # SOAP API service. It manages authentication, request/response handling, error handling,
+  # and provides automatic retry logic for transient failures.
+  #
+  # The client is built on top of the Savon SOAP library and includes:
+  # - Automatic authentication using WSSE (Web Service Security Extensions)
+  # - Intelligent retry logic for rate limiting and timeouts
+  # - Comprehensive error handling with specific exception types
+  # - Optional logging for debugging and monitoring
+  #
+  # @example Basic usage
+  #   client = Client.new(configuration)
+  #   response = client.call(:lihtandmed_v2, ariregistri_kood: '16863232')
+  #
+  # @example With custom configuration
+  #   config = Configuration.new
+  #   config.username = 'api_user'
+  #   config.password = 'api_pass' 
+  #   client = Client.new(config)
+  #
+  class Client
+    # @return [Configuration] The configuration object used by this client
+    attr_reader :config
+    
+    # @return [Savon::Client] The underlying Savon SOAP client for testing
+    attr_reader :savon_client
+    
+    # Initialize a new SOAP client with the provided configuration
+    #
+    # Sets up the underlying Savon SOAP client with proper authentication,
+    # timeouts, and error handling. The configuration is validated during
+    # initialization to ensure all required settings are present.
+    #
+    # @param config [Configuration] Configuration object with API credentials and settings
+    # @raise [ConfigurationError] If required configuration is missing or invalid
+    # @example
+    #   config = Configuration.new
+    #   config.username = 'myuser'
+    #   config.password = 'mypass'
+    #   client = Client.new(config)
+    #
+    def initialize(config = EeEBusinessRegister.configuration)
+      @config = config
+      
+      # Validate configuration only if it has credentials
+      config.validate! if config.credentials_configured?
+      
+      # Setup logging - use provided logger or create a null logger
+      @logger = config.logger || Logger.new(nil)
+      
+      # Create and configure the underlying Savon SOAP client
+      # with Estonian e-Business Register specific settings
+      if config.credentials_configured?
+        @savon_client = Savon.client(
+          wsdl: config.wsdl_url,                    # WSDL location for service definition
+          endpoint: config.endpoint_url,            # Actual service endpoint for requests
+          open_timeout: config.timeout,             # Connection timeout
+          read_timeout: config.timeout,             # Read timeout for responses
+          log: @logger.level == Logger::DEBUG,      # Enable Savon logging only in debug mode
+          logger: @logger,                          # Logger for Savon internal logging
+          wsse_auth: [config.username, config.password], # WS-Security authentication
+          namespace_identifier: :ns1,               # XML namespace prefix for requests
+          env_namespace: :soap,                     # SOAP envelope namespace
+          soap_version: 1,                          # Use SOAP 1.1 (required by Estonian API)
+          encoding: 'UTF-8',                        # Character encoding for XML
+          convert_request_keys_to: :none            # Preserve original key names in requests
+        )
+      else
+        @savon_client = nil
+      end
+    end
+    
+    # Check if the client is properly configured with valid credentials
+    #
+    # @return [Boolean] true if credentials are configured, false otherwise
+    def configured?
+      @config.credentials_configured?
+    end
+    
+    # Get list of available SOAP operations
+    #
+    # @return [Array<Symbol>] List of available operations from the WSDL
+    def operations
+      return [] unless @savon_client
+      @savon_client.operations
+    end
+    
+    # Execute a SOAP operation with automatic retry logic
+    #
+    # This method handles the actual SOAP request to the Estonian e-Business Register
+    # API. It includes intelligent retry logic for transient failures like rate limiting
+    # and timeouts, and converts various exception types into user-friendly APIErrors.
+    #
+    # The method automatically adds the configured language to all requests and
+    # handles the following error scenarios:
+    # - SOAP faults from the Estonian service
+    # - HTTP errors (401, 403, 429, 500, etc.)
+    # - Network timeouts with exponential backoff retry
+    # - Unexpected errors with proper logging
+    #
+    # @param operation [Symbol] The SOAP operation name to call (e.g., :lihtandmed_v2)
+    # @param message [Hash] Request parameters to send with the operation
+    # @return [Savon::Response] Raw SOAP response object
+    # @raise [APIError] For any API-related errors (authentication, service faults, etc.)
+    # 
+    # @example Find company by registry code
+    #   response = client.call(:lihtandmed_v2, ariregistri_kood: '16863232')
+    #   
+    # @example Search companies by name
+    #   response = client.call(:nimeparing_v1, nimi: 'Swedbank', max_arv: 10)
+    #
+    def call(operation, message = {})
+      # Ensure client is properly configured before making requests
+      unless configured?
+        raise AuthenticationError, 'Client is not properly configured. Please provide username and password.'
+      end
+      
+      retries = 0
+      max_retries = 3
+      
+      begin
+        # Log the operation being performed (if logging is enabled)
+        @logger.info "Calling #{operation} with params: #{message}" if @logger
+        
+        # Ensure all requests include the configured language
+        # This tells the Estonian API which language to use for responses
+        message[:keel] = @config.language unless message.key?(:keel)
+        
+        # Add authentication credentials to the message body
+        # The Estonian API expects credentials in the request body, not just WSSE headers
+        message[:ariregister_kasutajanimi] = @config.username
+        message[:ariregister_parool] = @config.password
+        
+        # All operations use the "keha" wrapper for consistency
+        # The Estonian API expects all parameters wrapped in "keha"
+        wrapped_message = {
+          keha: message
+        }
+        
+        # Execute the actual SOAP request via Savon
+        response = @savon_client.call(operation, message: wrapped_message)
+        
+        # Log successful response (debug level to avoid spam)
+        @logger.debug "Response received: #{response.body}" if @logger
+        
+        response
+        
+      rescue Savon::SOAPFault => e
+        # Handle SOAP faults from the Estonian service
+        # These usually indicate business logic errors (company not found, etc.)
+        @logger.error "SOAP Fault: #{e.message}" if @logger
+        raise APIError, "SOAP Fault: #{e.message}"
+        
+      rescue Savon::HTTPError => e
+        # Handle HTTP-level errors with special logic for rate limiting
+        if e.http.code == 429 && retries < max_retries
+          # Estonian API rate limiting - use exponential backoff
+          sleep_time = 2 ** retries
+          @logger.warn "Rate limited, retrying in #{sleep_time}s (attempt #{retries + 1}/#{max_retries})" if @logger
+          sleep(sleep_time)
+          retries += 1
+          retry
+        end
+        
+        # Log and re-raise other HTTP errors
+        @logger.error "HTTP Error: #{e.http.code} - #{e.message}" if @logger
+        raise APIError, "HTTP Error: #{e.http.code} - #{e.message}"
+        
+      rescue Timeout::Error, Net::ReadTimeout => e
+        # Handle network timeouts with retry logic
+        if retries < max_retries
+          retries += 1
+          @logger.warn "Timeout occurred, retrying (attempt #{retries}/#{max_retries})" if @logger
+          retry
+        end
+        
+        # Max retries exceeded - give up
+        @logger.error "Request timeout after #{max_retries} attempts: #{e.message}" if @logger
+        raise APIError, "Request timeout: #{e.message}"
+        
+      rescue => e
+        # Catch-all for unexpected errors - log details and re-raise as APIError
+        @logger.error "Unexpected error in SOAP call: #{e.class} - #{e.message}" if @logger
+        raise APIError, "Request failed: #{e.message}"
+      end
+    end
+    
+    # Check if the Estonian e-Business Register API is accessible and responding
+    #
+    # Performs a simple API call to verify that the service is available and
+    # responding correctly. Uses a well-known Estonian company registry code
+    # (Estonian Business Registry itself - 10060701) for the test.
+    #
+    # This method swallows all exceptions and returns a simple boolean,
+    # making it safe to use for health checks and monitoring.
+    #
+    # @return [Boolean] true if API is accessible and responding, false otherwise
+    # @example
+    #   if client.healthy?
+    #     puts "API is working"
+    #   else
+    #     puts "API is down or unreachable"
+    #   end
+    #
+    def healthy?
+      # Use Estonian Business Registry's own registry code for health check
+      # This is a stable, well-known entity that should always exist
+      call(:lihtandmed_v2, ariregistri_kood: '10060701')
+      true
+    rescue
+      # Any error means the API is not healthy
+      false
+    end
+  end
+  
+end

data/lib/ee_e_business_register/configuration.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module EeEBusinessRegister
+  # Configuration class for the Estonian e-Business Register API client
+  #
+  # This class handles all configuration options required to connect to and interact
+  # with the Estonian e-Business Register SOAP API service. It supports both
+  # production and test environments with sensible defaults.
+  #
+  # @example Basic configuration
+  #   config = Configuration.new
+  #   config.username = 'your_username'
+  #   config.password = 'your_password'
+  #   config.validate!
+  #
+  # @example Test mode configuration
+  #   config = Configuration.new
+  #   config.username = 'test_user'
+  #   config.password = 'test_pass'
+  #   config.test_mode!
+  #
+  class Configuration
+    # API authentication credentials - required for all API calls
+    # @return [String] API username provided by Estonian Business Registry
+    attr_accessor :username
+    
+    # @return [String] API password provided by Estonian Business Registry  
+    attr_accessor :password
+    
+    # SOAP service endpoints for the Estonian e-Business Register
+    # @return [String] WSDL URL for service definition (auto-set based on environment)
+    attr_accessor :wsdl_url
+    
+    # @return [String] Endpoint URL for actual API calls (auto-set based on environment)
+    attr_accessor :endpoint_url
+    
+    # API request configuration options
+    # @return [String] Response language: 'eng' for English, 'est' for Estonian (default: 'eng')
+    attr_accessor :language
+    
+    # @return [Integer] HTTP request timeout in seconds (default: 30)
+    attr_accessor :timeout
+    
+    # @return [Boolean] Whether using test environment endpoints (default: false)
+    attr_accessor :test_mode
+    
+    # @return [Logger, nil] Optional logger instance for debugging API calls (default: nil)
+    attr_accessor :logger
+    
+    # Initialize configuration with production defaults
+    #
+    # Sets up the configuration with sensible defaults for production use.
+    # You must set username and password before making API calls.
+    #
+    def initialize
+      # Production API endpoints - official Estonian e-Business Register
+      @wsdl_url = 'https://ariregxmlv6.rik.ee/?wsdl'
+      @endpoint_url = 'https://ariregxmlv6.rik.ee/'
+      
+      # Default to English responses and 30-second timeout
+      @language = 'eng'
+      @timeout = 30
+      
+      # Start in production mode without logging
+      @test_mode = false
+      @logger = nil
+    end
+    
+    # Switch to test environment endpoints
+    #
+    # Changes the WSDL and endpoint URLs to use the Estonian e-Business Register
+    # test environment. Useful for development and testing without affecting
+    # production data or hitting rate limits.
+    #
+    # @return [Boolean] Always returns true
+    # @example
+    #   config = Configuration.new
+    #   config.test_mode!
+    #   # Now uses test endpoints
+    #
+    def test_mode!
+      @test_mode = true
+      @wsdl_url = 'https://demo-ariregxmlv6.rik.ee/?wsdl'
+      @endpoint_url = 'https://demo-ariregxmlv6.rik.ee/'
+    end
+    
+    # Validate that all required configuration is present and valid
+    #
+    # Checks that username and password are provided and that language
+    # is one of the supported options. Should be called before making
+    # any API requests to ensure proper configuration.
+    #
+    # @return [Boolean] Returns true if valid
+    # @raise [ConfigurationError] If any required setting is missing or invalid
+    # @example
+    #   config.username = 'myuser'
+    #   config.password = 'mypass'
+    #   config.validate! # => true
+    #
+    def validate!
+      # Ensure API credentials are provided
+      raise ConfigurationError, 'Username is required' if username.nil? || username.empty?
+      raise ConfigurationError, 'Password is required' if password.nil? || password.empty?
+      
+      # Validate language setting
+      unless %w[eng est].include?(language)
+        raise ConfigurationError, 'Language must be eng (English) or est (Estonian)'
+      end
+      
+      true
+    end
+    
+    # Switch to production environment endpoints
+    #
+    # Switches back to production URLs after being in test mode
+    # @return [Boolean] Always returns true
+    def production_mode!
+      @test_mode = false
+      @wsdl_url = 'https://ariregxmlv6.rik.ee/?wsdl'
+      @endpoint_url = 'https://ariregxmlv6.rik.ee/'
+    end
+    
+    # Check if we're in test mode
+    #
+    # @return [Boolean] true if in test mode, false otherwise
+    def test_mode?
+      @test_mode == true
+    end
+    
+    # Check if we're in production mode
+    #
+    # @return [Boolean] true if in production mode, false otherwise  
+    def production_mode?
+      @test_mode != true
+    end
+    
+    # Check if credentials are properly configured
+    #
+    # @return [Boolean] true if both username and password are present
+    def credentials_configured?
+      !username.nil? && !username.empty? && !password.nil? && !password.empty?
+    end
+    
+    # Export configuration as hash
+    #
+    # @return [Hash] Configuration values with password masked for security
+    def to_h
+      {
+        wsdl_url: @wsdl_url,
+        endpoint_url: @endpoint_url,
+        language: @language,
+        timeout: @timeout,
+        username: @username,
+        password: @password.nil? ? nil : "[MASKED]",
+        environment: test_mode? ? "test" : "production"
+      }
+    end
+  end
+  
+end

data/lib/ee_e_business_register/errors.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module EeEBusinessRegister
+  # Base exception class for all Estonian e-Business Register gem errors
+  #
+  # This serves as the parent class for all custom exceptions raised by the gem.
+  # Catching this exception will capture any error originating from the gem's
+  # internal operations, making it useful for general error handling.
+  #
+  # @example Catch all gem-related errors
+  #   begin
+  #     company = EeEBusinessRegister.find_company('16863232')
+  #   rescue EeEBusinessRegister::Error => e
+  #     puts "Estonian register error: #{e.message}"
+  #   end
+  #
+  class Error < StandardError; end
+  
+  # Raised when API authentication fails
+  #
+  # This exception is thrown when the Estonian e-Business Register API
+  # rejects the provided username and password credentials. Common causes:
+  # - Incorrect username or password
+  # - Account suspended or expired  
+  # - Network issues preventing proper authentication
+  #
+  # @example Handle authentication errors
+  #   begin
+  #     EeEBusinessRegister.find_company('16863232')
+  #   rescue EeEBusinessRegister::AuthenticationError
+  #     puts "Please check your API credentials"
+  #   end
+  #
+  class AuthenticationError < Error; end
+  
+  # Raised for all Estonian API communication and service errors
+  #
+  # This is the most common exception type, covering various API-related failures:
+  # - Network connectivity issues
+  # - Estonian service downtime or maintenance
+  # - Rate limiting (too many requests)
+  # - SOAP service faults (data not found, invalid requests)
+  # - HTTP errors (500, 503, etc.)
+  # - Request timeouts
+  #
+  # The error message typically includes specific details about what went wrong
+  # and suggestions for resolution (retry later, check parameters, etc.).
+  #
+  # @example Handle API errors gracefully
+  #   begin
+  #     company = EeEBusinessRegister.find_company('16863232')
+  #   rescue EeEBusinessRegister::APIError => e
+  #     if e.message.include?("timeout")
+  #       puts "Service is slow, please try again"
+  #     elsif e.message.include?("not found") 
+  #       puts "Company does not exist"
+  #     else
+  #       puts "API error: #{e.message}"
+  #     end
+  #   end
+  #
+  class APIError < Error; end
+  
+  # Raised when gem configuration is invalid or incomplete
+  #
+  # This exception occurs when required configuration settings are missing
+  # or have invalid values. Most commonly raised during initial setup when
+  # username, password, or other required settings are not provided.
+  #
+  # @example Handle configuration errors
+  #   begin
+  #     EeEBusinessRegister.configure do |config|
+  #       config.username = nil  # This will cause an error
+  #     end
+  #   rescue EeEBusinessRegister::ConfigurationError => e
+  #     puts "Configuration problem: #{e.message}"
+  #   end
+  #
+  class ConfigurationError < Error; end
+  
+  # Raised when user input fails validation rules
+  #
+  # This exception is thrown when user-provided data doesn't meet the
+  # required format or contains potentially dangerous content. Examples:
+  # - Registry codes that aren't exactly 8 digits
+  # - Invalid date formats
+  # - Empty or malformed search queries
+  # - Input that could cause security issues
+  #
+  # @example Handle validation errors  
+  #   begin
+  #     company = EeEBusinessRegister.find_company('invalid-code')
+  #   rescue EeEBusinessRegister::ValidationError => e
+  #     puts "Input error: #{e.message}"
+  #   end
+  #
+  class ValidationError < Error; end
+end

data/lib/ee_e_business_register/models/classifier.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+module EeEBusinessRegister
+  module Models
+    class ClassifierValue < Dry::Struct
+      attribute :code, Types::String
+      attribute :name, Types::String
+      attribute :valid_from, Types::String.optional
+      attribute :valid_to, Types::String.optional.default(nil)
+    end
+
+    class Classifier < Dry::Struct
+      attribute :code, Types::String
+      attribute :name, Types::String
+      attribute :values, Types::Array.of(ClassifierValue)
+
+      def find_value(code)
+        values.find { |v| v.code == code }
+      end
+
+      def active_values
+        values.select { |v| v.valid_to.nil? }
+      end
+    end
+  end
+end