cuzk-soap 0.1.0

data/lib/cuzk/soap/client.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    class Client
+      attr_reader :configuration, :connection, :cost_manager
+
+      def initialize(username: nil, password: nil, environment: nil, **options)
+        @configuration = CUZK::SOAP.configuration.dup
+        @configuration.username = username if username
+        @configuration.password = password if password
+        @configuration.environment = environment if environment
+
+        options.each do |key, value|
+          @configuration.public_send(:"#{key}=", value) if @configuration.respond_to?(:"#{key}=")
+        end
+
+        @configuration.validate!
+        @connection = Connection.new(@configuration)
+        @cost_manager = CostManager.new(@configuration)
+        @services = {}
+      end
+
+      # --- Service accessors ---
+
+      def search_service
+        @services[:search] ||= Services::SearchService.new(@connection)
+      end
+
+      def report_service
+        @services[:report] ||= Services::ReportService.new(@connection)
+      end
+
+      def account_service
+        @services[:account] ||= Services::AccountService.new(@connection)
+      end
+
+      def informace_service
+        @services[:informace] ||= Services::InformaceService.new(@connection)
+      end
+
+      def ciselnik_service
+        @services[:ciselnik] ||= Services::CiselnikService.new(@connection)
+      end
+
+      # --- Account management ---
+
+      def account_status
+        account_service.stav_ws
+      end
+
+      def change_password(old_password:, new_password:)
+        account_service.zmen_heslo(stare_heslo: old_password, nove_heslo: new_password)
+      end
+
+      def cost_estimate(operations)
+        @cost_manager.estimate_batch_cost(operations)
+      end
+
+      # --- Search operations ---
+
+      def search_parcel(cadastral_unit_code: nil, parcel_number: nil, parcel_id: nil, **)
+        search_service.najdi_parcelu(
+          katastr_uzemi_kod: cadastral_unit_code,
+          kmenove_cislo: parcel_number,
+          parcela_id: parcel_id,
+          **
+        )
+      end
+
+      def search_building(building_id: nil, district_part_code: nil, building_type_code: nil,
+                          building_number: nil, **)
+        search_service.najdi_stavbu(
+          stavba_id: building_id,
+          cast_obce_kod: district_part_code,
+          typ_stavby_kod: building_type_code,
+          cislo_domovni: building_number,
+          **
+        )
+      end
+
+      def search_unit(cadastral_unit_code: nil, unit_number: nil, unit_id: nil, **)
+        search_service.najdi_jednotku(
+          katastr_uzemi_kod: cadastral_unit_code,
+          cislo_jednotky: unit_number,
+          jednotka_id: unit_id,
+          **
+        )
+      end
+
+      def search_subject(**params)
+        search_service.najdi_os(**params)
+      end
+
+      # --- Report generation (async) ---
+
+      def generate_lv(lv_id:, format: 'pdf', **options)
+        with_cost_control(:lv_extract_pdf) do
+          report_service.generuj_lv(lv_id: lv_id, format: format, **options)
+        end
+      end
+
+      def generate_parcel_info(format: 'pdf', **options)
+        with_cost_control(:property_info) do
+          report_service.generuj_info_o_parcelach(format: format, **options)
+        end
+      end
+
+      def generate_building_info(format: 'pdf', **options)
+        with_cost_control(:building_info) do
+          report_service.generuj_info_o_stavbach(format: format, **options)
+        end
+      end
+
+      def generate_unit_info(jednotka_id:, format: 'pdf', **options)
+        with_cost_control(:unit_info) do
+          report_service.generuj_info_o_jednotkach(jednotka_id: jednotka_id, format: format, **options)
+        end
+      end
+
+      # --- Report management ---
+
+      def list_reports(id_sestavy: nil)
+        report_service.seznam_sestav(id_sestavy: id_sestavy)
+      end
+
+      def download_report(id_sestavy:)
+        report_service.vrat_sestavu(id_sestavy: id_sestavy)
+      end
+
+      def delete_report(id_sestavy:)
+        report_service.smaz_sestavu(id_sestavy: id_sestavy)
+      end
+
+      # --- Codelist operations ---
+
+      def list_cadastral_units
+        ciselnik_service.seznam_ku
+      end
+
+      # --- Batch processing ---
+
+      def batch_generate(operations, &progress_block)
+        processor = BatchProcessor.new(self, operations)
+        processor.on_progress(&progress_block) if progress_block
+        processor.start
+      end
+
+      # --- Monitoring ---
+
+      def service_status
+        {
+          environment: @configuration.environment,
+          wsdp_version: @configuration.wsdp_version,
+          connected: connection_alive?,
+          cost_manager: {
+            daily_spent: @cost_manager.daily_spent,
+            monthly_spent: @cost_manager.monthly_spent,
+            daily_remaining: @cost_manager.daily_budget_remaining,
+            monthly_remaining: @cost_manager.monthly_budget_remaining,
+            budget_alert: @cost_manager.budget_alert?
+          }
+        }
+      end
+
+      def wsdp_version_info
+        {
+          version: @configuration.wsdp_version,
+          available_services: @connection.wsdl_manager.available_services,
+          wsdl_urls: @connection.wsdl_manager.all_wsdl_urls,
+          soap_endpoints: @connection.wsdl_manager.all_soap_endpoints
+        }
+      end
+
+      private
+
+      def with_cost_control(operation, count: 1)
+        estimated = @cost_manager.estimate_cost(operation, count: count)
+
+        @cost_manager.check_budget!(estimated) if @configuration.auto_pause_on_budget_exceeded
+
+        result = yield
+
+        @cost_manager.record_transaction(operation, estimated)
+        result
+      end
+
+      def connection_alive?
+        account_service.stav_ws
+        true
+      rescue Error
+        false
+      end
+    end
+  end
+end

data/lib/cuzk/soap/configuration.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    class Configuration
+      # WSDP account credentials
+      attr_accessor :username, :password
+
+      # Environment: :production or :testing
+      attr_accessor :environment
+
+      # WSDP version: :v31 or :v29
+      attr_accessor :wsdp_version
+
+      # Cost management (CZK)
+      attr_accessor :daily_budget_limit, :monthly_budget_limit,
+                    :cost_alert_threshold, :auto_pause_on_budget_exceeded
+
+      # SOAP client settings (WSDP uses SOAP 1.1 only)
+      attr_accessor :open_timeout, :read_timeout,
+                    :max_retries, :retry_delay,
+                    :ssl_verify_mode
+
+      # WSDP features
+      attr_accessor :validate_wsdl_on_startup, :cache_wsdl, :wsdl_cache_ttl
+
+      # Enterprise features
+      attr_accessor :audit_logging, :audit_log_path,
+                    :performance_monitoring, :compliance_mode, :gdpr_anonymization
+
+      # Caching
+      attr_accessor :cache_store, :cache_ttl_extracts, :cache_ttl_searches,
+                    :cache_ttl_account_status
+
+      # Logging
+      attr_accessor :logger, :log_level
+
+      # Rate limiting
+      attr_accessor :requests_per_minute, :concurrent_requests
+
+      # Circuit breaker
+      attr_accessor :circuit_breaker_threshold, :circuit_breaker_timeout
+
+      # Enabled services
+      attr_accessor :enabled_services
+
+      def initialize
+        @environment = :production
+        @wsdp_version = :v31
+
+        # Cost management defaults
+        @daily_budget_limit = nil
+        @monthly_budget_limit = nil
+        @cost_alert_threshold = 0.8
+        @auto_pause_on_budget_exceeded = false
+
+        # SOAP defaults (WSDP uses SOAP 1.1 exclusively)
+        @open_timeout = 30
+        @read_timeout = 120
+        @max_retries = 3
+        @retry_delay = 2
+        @ssl_verify_mode = :peer
+
+        # WSDP feature defaults
+        @validate_wsdl_on_startup = false
+        @cache_wsdl = true
+        @wsdl_cache_ttl = 86_400 # 24 hours in seconds
+
+        # Enterprise defaults
+        @audit_logging = false
+        @performance_monitoring = false
+        @compliance_mode = :standard
+        @gdpr_anonymization = true
+
+        # Caching defaults (seconds)
+        @cache_ttl_extracts = 1800       # 30 minutes
+        @cache_ttl_searches = 900        # 15 minutes
+        @cache_ttl_account_status = 300  # 5 minutes
+
+        # Logging defaults
+        @log_level = :info
+
+        # Rate limiting defaults
+        @requests_per_minute = 120
+        @concurrent_requests = 10
+
+        # Circuit breaker defaults
+        @circuit_breaker_threshold = 10
+        @circuit_breaker_timeout = 60
+
+        # All services enabled by default
+        @enabled_services = %i[vyhledat sestavy informace ciselnik ucet]
+      end
+
+      def production?
+        environment == :production
+      end
+
+      def testing?
+        environment == :testing
+      end
+
+      def validate!
+        raise ConfigurationError, 'username is required' if username.nil? || username.empty?
+        raise ConfigurationError, 'password is required' if password.nil? || password.empty?
+
+        unless %i[production testing].include?(environment)
+          raise ConfigurationError, 'environment must be :production or :testing'
+        end
+
+        raise ConfigurationError, 'wsdp_version must be :v31 or :v29' unless %i[v31 v29].include?(wsdp_version)
+
+        true
+      end
+    end
+  end
+end

data/lib/cuzk/soap/connection.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'savon'
+require 'retriable'
+
+module CUZK
+  module SOAP
+    class Connection
+      attr_reader :wsdl_manager, :credentials
+
+      def initialize(configuration)
+        @configuration = configuration
+        @wsdl_manager = WSDLManager.new(
+          version: configuration.wsdp_version,
+          environment: configuration.environment
+        )
+        @credentials = Authentication::WSDPCredentials.new(
+          username: configuration.username,
+          password: configuration.password,
+          environment: configuration.environment
+        )
+        @clients = {}
+        @circuit_breaker_failures = 0
+        @circuit_breaker_opened_at = nil
+      end
+
+      def call(service, operation, message = {})
+        check_circuit_breaker!
+
+        with_retry do
+          client = client_for(service)
+          response = client.call(operation, message: message)
+          reset_circuit_breaker
+          response
+        end
+      rescue Savon::SOAPFault => e
+        handle_soap_fault(e)
+      rescue Savon::HTTPError => e
+        record_failure
+        raise ServiceUnavailableError.new(
+          "HTTP error: #{e.message}",
+          fault_code: e.http.code.to_s
+        )
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        record_failure
+        raise NetworkTimeoutError, "Request timed out: #{e.message}"
+      end
+
+      def client_for(service)
+        @clients[service] ||= build_savon_client(service)
+      end
+
+      def available_operations(service)
+        client_for(service).operations
+      rescue StandardError => e
+        raise WSDPError, "Failed to retrieve operations for #{service}: #{e.message}"
+      end
+
+      private
+
+      def build_savon_client(service)
+        wsdl_url = @wsdl_manager.wsdl_url(service)
+        # ČÚZK WSDLs use separate namespaces for service definitions and types.
+        # Savon defaults to the WSDL targetNamespace (services:*) but request
+        # elements must use the types namespace (types:*).
+        types_ns = @wsdl_manager.types_namespace(service)
+
+        Savon.client(
+          wsdl: wsdl_url,
+          namespace: types_ns,
+          wsse_auth: @credentials.savon_wsse_auth,
+          soap_version: 1, # WSDP uses SOAP 1.1 exclusively
+          open_timeout: @configuration.open_timeout,
+          read_timeout: @configuration.read_timeout,
+          encoding: 'UTF-8',
+          log: !@configuration.logger.nil?,
+          logger: @configuration.logger || Logger.new(File::NULL),
+          log_level: @configuration.log_level,
+          pretty_print_xml: true,
+          ssl_verify_mode: @configuration.ssl_verify_mode,
+          convert_request_keys_to: :none
+        )
+      end
+
+      def with_retry(&)
+        Retriable.retriable(
+          tries: @configuration.max_retries + 1,
+          base_interval: @configuration.retry_delay,
+          multiplier: 2.0,
+          on: [NetworkTimeoutError, ServiceUnavailableError],
+          &
+        )
+      end
+
+      def handle_soap_fault(error)
+        fault = error.to_hash[:fault] || {}
+        fault_code = fault[:faultcode].to_s
+        fault_string = fault[:faultstring].to_s
+
+        exception_class = case fault_code
+                          when /InsufficientFunds/i then InsufficientFundsError
+                          when /AccountSuspended/i then AccountSuspendedError
+                          when /Authentication/i then AuthenticationError
+                          when /InvalidRequest/i then InvalidRequestError
+                          else WSDPError
+                          end
+
+        record_failure
+        raise exception_class.new(fault_string, fault_code: fault_code, fault_string: fault_string)
+      end
+
+      def check_circuit_breaker!
+        return unless @circuit_breaker_opened_at
+
+        elapsed = Time.now - @circuit_breaker_opened_at
+        if elapsed >= @configuration.circuit_breaker_timeout
+          @circuit_breaker_opened_at = nil
+          @circuit_breaker_failures = 0
+        else
+          raise CircuitBreakerOpenError,
+                "Circuit breaker is open. Retry after #{(@configuration.circuit_breaker_timeout - elapsed).ceil}s"
+        end
+      end
+
+      def record_failure
+        @circuit_breaker_failures += 1
+        return unless @circuit_breaker_failures >= @configuration.circuit_breaker_threshold
+
+        @circuit_breaker_opened_at = Time.now
+      end
+
+      def reset_circuit_breaker
+        @circuit_breaker_failures = 0
+        @circuit_breaker_opened_at = nil
+      end
+    end
+  end
+end

data/lib/cuzk/soap/cost_manager.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    class CostManager
+      # Approximate WSDP pricing in CZK (actual prices per ČÚZK sazebník)
+      WSDP_PRICING = {
+        lv_extract_pdf: 50.0,
+        lv_extract_xml: 50.0,
+        property_info: 30.0,
+        building_info: 30.0,
+        unit_info: 30.0,
+        ownership_overview: 100.0,
+        ownership_with_properties: 100.0,
+        price_data: 40.0,
+        account_status: 0.0,
+        document_order: 0.0
+      }.freeze
+
+      attr_reader :daily_spent, :monthly_spent, :transaction_log
+
+      def initialize(configuration)
+        @configuration = configuration
+        @daily_spent = 0.0
+        @monthly_spent = 0.0
+        @transaction_log = []
+        @daily_reset_at = today_start
+        @monthly_reset_at = month_start
+      end
+
+      def estimate_cost(operation, count: 1)
+        unit_cost = WSDP_PRICING.fetch(operation, 0.0)
+        unit_cost * count
+      end
+
+      def estimate_batch_cost(operations)
+        operations.sum { |op, count| estimate_cost(op, count: count) }
+      end
+
+      def check_budget!(estimated_cost)
+        reset_counters_if_needed
+
+        if @configuration.daily_budget_limit && (daily_spent + estimated_cost) > @configuration.daily_budget_limit
+          raise CostLimitExceededError,
+                "Daily budget limit would be exceeded: #{daily_spent + estimated_cost} CZK " \
+                "(limit: #{@configuration.daily_budget_limit} CZK)"
+        end
+
+        if @configuration.monthly_budget_limit && (monthly_spent + estimated_cost) > @configuration.monthly_budget_limit
+          raise CostLimitExceededError,
+                "Monthly budget limit would be exceeded: #{monthly_spent + estimated_cost} CZK " \
+                "(limit: #{@configuration.monthly_budget_limit} CZK)"
+        end
+
+        true
+      end
+
+      def record_transaction(operation, cost, metadata = {})
+        reset_counters_if_needed
+
+        @daily_spent += cost
+        @monthly_spent += cost
+        @transaction_log << {
+          operation: operation,
+          cost: cost,
+          timestamp: Time.now.utc,
+          metadata: metadata
+        }
+      end
+
+      def budget_alert?
+        return false unless @configuration.cost_alert_threshold
+
+        threshold = @configuration.cost_alert_threshold
+
+        if @configuration.daily_budget_limit && (daily_spent >= (@configuration.daily_budget_limit * threshold))
+          return true
+        end
+
+        if @configuration.monthly_budget_limit && (monthly_spent >= (@configuration.monthly_budget_limit * threshold))
+          return true
+        end
+
+        false
+      end
+
+      def daily_budget_remaining
+        return Float::INFINITY unless @configuration.daily_budget_limit
+
+        [@configuration.daily_budget_limit - daily_spent, 0.0].max
+      end
+
+      def monthly_budget_remaining
+        return Float::INFINITY unless @configuration.monthly_budget_limit
+
+        [@configuration.monthly_budget_limit - monthly_spent, 0.0].max
+      end
+
+      def reset_daily!
+        @daily_spent = 0.0
+        @daily_reset_at = today_start
+      end
+
+      def reset_monthly!
+        @monthly_spent = 0.0
+        @monthly_reset_at = month_start
+      end
+
+      private
+
+      def reset_counters_if_needed
+        now = Time.now.utc
+
+        if now >= @daily_reset_at + 86_400
+          @daily_spent = 0.0
+          @daily_reset_at = today_start
+        end
+
+        return unless now.month != @monthly_reset_at.month || now.year != @monthly_reset_at.year
+
+        @monthly_spent = 0.0
+        @monthly_reset_at = month_start
+      end
+
+      def today_start
+        now = Time.now.utc
+        Time.utc(now.year, now.month, now.day)
+      end
+
+      def month_start
+        now = Time.now.utc
+        Time.utc(now.year, now.month, 1)
+      end
+    end
+  end
+end

data/lib/cuzk/soap/document_manager.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'fileutils'
+
+module CUZK
+  module SOAP
+    class DocumentManager
+      attr_reader :storage_path
+
+      def initialize(storage_path: nil)
+        @storage_path = storage_path
+        @documents = {}
+      end
+
+      def store(document_id, content, format:, metadata: {})
+        entry = {
+          content: content,
+          format: format,
+          stored_at: Time.now.utc,
+          size: content.bytesize,
+          metadata: metadata
+        }
+
+        @documents[document_id] = entry
+
+        write_to_disk(document_id, content, format) if @storage_path
+
+        entry
+      end
+
+      def retrieve(document_id)
+        entry = @documents[document_id]
+        return entry if entry
+
+        return unless @storage_path
+
+        read_from_disk(document_id)
+      end
+
+      def delete(document_id)
+        @documents.delete(document_id)
+
+        return unless @storage_path
+
+        delete_from_disk(document_id)
+      end
+
+      def list(filter: nil)
+        docs = @documents.map do |id, entry|
+          {
+            document_id: id,
+            format: entry[:format],
+            stored_at: entry[:stored_at],
+            size: entry[:size],
+            metadata: entry[:metadata]
+          }
+        end
+
+        if filter
+          docs.select { |d| d[:format].to_s == filter.to_s }
+        else
+          docs
+        end
+      end
+
+      def save_to_file(document_id, file_path)
+        entry = retrieve(document_id)
+        raise DocumentError, "Document not found: #{document_id}" unless entry
+
+        File.binwrite(file_path, entry[:content])
+        file_path
+      end
+
+      private
+
+      def write_to_disk(document_id, content, format)
+        FileUtils.mkdir_p(@storage_path)
+        file_path = File.join(@storage_path, "#{sanitize_id(document_id)}.#{format}")
+        File.binwrite(file_path, content)
+      end
+
+      def read_from_disk(document_id)
+        Dir.glob(File.join(@storage_path, "#{sanitize_id(document_id)}.*")).first&.then do |path|
+          {
+            content: File.binread(path),
+            format: File.extname(path).delete('.'),
+            stored_at: File.mtime(path),
+            size: File.size(path),
+            metadata: {}
+          }
+        end
+      end
+
+      def delete_from_disk(document_id)
+        Dir.glob(File.join(@storage_path, "#{sanitize_id(document_id)}.*")).each do |path|
+          File.delete(path)
+        end
+      end
+
+      def sanitize_id(document_id)
+        document_id.to_s.gsub(/[^a-zA-Z0-9_-]/, '_')
+      end
+    end
+  end
+end