cuzk-soap 0.1.0

data/lib/cuzk/soap/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    class Error < StandardError; end
+
+    # WSDP service errors
+    class WSDPError < Error
+      attr_reader :fault_code, :fault_string
+
+      def initialize(message = nil, fault_code: nil, fault_string: nil)
+        @fault_code = fault_code
+        @fault_string = fault_string
+        super(message || fault_string)
+      end
+    end
+
+    class AccountError < WSDPError; end
+    class InsufficientFundsError < AccountError; end
+    class AccountSuspendedError < AccountError; end
+    class ServiceUnavailableError < WSDPError; end
+    class InvalidRequestError < WSDPError; end
+
+    # Document errors
+    class DocumentError < Error; end
+    class ExtractGenerationError < DocumentError; end
+    class InvalidPropertyError < DocumentError; end
+    class CertificationError < DocumentError; end
+
+    # Professional service errors
+    class BatchProcessingError < Error; end
+    class CostLimitExceededError < Error; end
+    class ComplianceViolationError < Error; end
+    class IntegrationError < Error; end
+
+    # Infrastructure errors
+    class SOAPError < Error; end
+    class AuthenticationError < SOAPError; end
+    class CertificateError < SOAPError; end
+    class NetworkTimeoutError < SOAPError; end
+    class CircuitBreakerOpenError < SOAPError; end
+    class MaxRetriesExceededError < SOAPError; end
+
+    # Configuration errors
+    class ConfigurationError < Error; end
+  end
+end

data/lib/cuzk/soap/property_report.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    class PropertyReport
+      attr_reader :property_id, :property_type, :raw_data, :generated_at
+
+      def initialize(property_id:, property_type:, raw_data:)
+        @property_id = property_id
+        @property_type = property_type
+        @raw_data = raw_data
+        @generated_at = Time.now.utc
+      end
+
+      def self.for_parcel(client, katastr_uzemi_kod:, kmenove_cislo:, format: 'xml')
+        raw_data = client.report_service.informace_o_parcele(
+          katastr_uzemi_kod: katastr_uzemi_kod,
+          kmenove_cislo: kmenove_cislo,
+          format: format
+        )
+
+        new(
+          property_id: "#{katastr_uzemi_kod}/#{kmenove_cislo}",
+          property_type: :parcel,
+          raw_data: raw_data
+        )
+      end
+
+      def self.for_building(client, katastr_uzemi_kod:, cislo_budovy:, format: 'xml')
+        raw_data = client.report_service.informace_o_budove(
+          katastr_uzemi_kod: katastr_uzemi_kod,
+          cislo_budovy: cislo_budovy,
+          format: format
+        )
+
+        new(
+          property_id: "#{katastr_uzemi_kod}/#{cislo_budovy}",
+          property_type: :building,
+          raw_data: raw_data
+        )
+      end
+
+      def self.for_unit(client, jednotka_id:, format: 'xml')
+        raw_data = client.report_service.informace_o_jednotce(
+          jednotka_id: jednotka_id,
+          format: format
+        )
+
+        new(
+          property_id: jednotka_id.to_s,
+          property_type: :unit,
+          raw_data: raw_data
+        )
+      end
+
+      def basic_info
+        extract_section(:zakladni_informace) || extract_section(:basic_info)
+      end
+
+      def location_info
+        extract_section(:umisteni) || extract_section(:location)
+      end
+
+      def ownership
+        extract_section(:vlastnictvi) || extract_section(:ownership)
+      end
+
+      def encumbrances
+        extract_section(:omezeni) || extract_section(:encumbrances) || []
+      end
+
+      def to_h
+        {
+          property_id: @property_id,
+          property_type: @property_type,
+          generated_at: @generated_at,
+          data: @raw_data
+        }
+      end
+
+      private
+
+      def extract_section(key)
+        return nil unless @raw_data.is_a?(Hash)
+
+        @raw_data[key] || @raw_data[key.to_s]
+      end
+    end
+  end
+end

data/lib/cuzk/soap/services/account_service.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    module Services
+      class AccountService < BaseService
+        def stav_ws
+          call_operation(:stav_ws, {})
+        end
+        alias account_status stav_ws
+
+        def zmen_heslo(stare_heslo:, nove_heslo:)
+          message = {
+            stareHeslo: stare_heslo,
+            noveHeslo: nove_heslo
+          }
+
+          call_operation(:zmen_heslo, message)
+        end
+        alias change_password zmen_heslo
+
+        private
+
+        def service_name
+          :ucet
+        end
+      end
+    end
+  end
+end

data/lib/cuzk/soap/services/base_service.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    module Services
+      class BaseService
+        attr_reader :connection
+
+        def initialize(connection)
+          @connection = connection
+        end
+
+        private
+
+        def call_operation(operation, message = {})
+          response = connection.call(service_name, operation, message)
+          parse_response(response)
+        end
+
+        def parse_response(response)
+          body = response.body
+          return body if body.is_a?(Hash)
+
+          body
+        end
+
+        def extract_document(response, format)
+          body = response.body
+          case format.to_s
+          when 'pdf'
+            extract_pdf(body)
+          when 'xml'
+            extract_xml(body)
+          when 'html'
+            extract_html(body)
+          else
+            body
+          end
+        end
+
+        def extract_pdf(body)
+          # WSDP returns PDF as base64-encoded MTOM attachment or inline
+          find_binary_content(body)
+        end
+
+        def extract_xml(body)
+          find_content(body)
+        end
+
+        def extract_html(body)
+          find_content(body)
+        end
+
+        def find_binary_content(data)
+          return Base64.decode64(data) if data.is_a?(String)
+
+          if data.is_a?(Hash)
+            data.each_value do |value|
+              result = find_binary_content(value)
+              return result if result
+            end
+          end
+
+          nil
+        end
+
+        def find_content(data)
+          return data if data.is_a?(String)
+
+          if data.is_a?(Hash)
+            data.each_value do |value|
+              result = find_content(value)
+              return result if result
+            end
+          end
+
+          nil
+        end
+
+        def service_name
+          raise NotImplementedError, "#{self.class} must implement #service_name"
+        end
+      end
+    end
+  end
+end

data/lib/cuzk/soap/services/ciselnik_service.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    module Services
+      class CiselnikService < BaseService
+        def seznam_ku
+          call_operation(:seznam_ku, {})
+        end
+        alias list_cadastral_units seznam_ku
+
+        private
+
+        def service_name
+          :ciselnik
+        end
+      end
+    end
+  end
+end

data/lib/cuzk/soap/services/informace_service.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    module Services
+      class InformaceService < BaseService
+        def cti_os(opravneny_subjekt_id:)
+          call_operation(:cti_os, { opravnenySubjektId: opravneny_subjekt_id })
+        end
+        alias read_subject cti_os
+
+        private
+
+        def service_name
+          :informace
+        end
+      end
+    end
+  end
+end

data/lib/cuzk/soap/services/report_service.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    module Services
+      # ReportService wraps the WSDP "sestavy" service.
+      # Report generation is ASYNCHRONOUS:
+      #   1. Call generuj* to request generation -> returns request metadata
+      #   2. Poll seznam_sestav to check if the report is ready
+      #   3. Call vrat_sestavu to download the finished report
+      #   4. Optionally call smaz_sestavu to clean up
+      class ReportService < BaseService
+        VALID_FORMATS = %w[pdf xml html zip].freeze
+
+        # --- Report generation requests ---
+
+        def generuj_lv(lv_id:, format: 'pdf', **options)
+          validate_format!(format)
+          message = { lvId: lv_id, format: format }.merge(options)
+
+          call_operation(:generuj_lv, message)
+        end
+        alias generate_lv generuj_lv
+
+        # Find parcel by parcelaId OR katastrUzemiKod + kmenoveCislo
+        def generuj_info_o_parcelach(format: 'pdf', parcela_id: nil,
+                                     katastr_uzemi_kod: nil, kmenove_cislo: nil, **options)
+          validate_format!(format)
+          message = if parcela_id
+                      { parcelaId: parcela_id }
+                    else
+                      { katastrUzemiKod: katastr_uzemi_kod, kmenoveCislo: kmenove_cislo }
+                    end
+          message[:format] = format
+          message.merge!(options)
+
+          call_operation(:generuj_info_o_parcelach, message)
+        end
+        alias generate_parcel_info generuj_info_o_parcelach
+
+        def generuj_info_o_stavbach(format: 'pdf', stavba_id: nil,
+                                    cast_obce_kod: nil, typ_stavby_kod: nil, cislo_domovni: nil, **options)
+          validate_format!(format)
+          message = if stavba_id
+                      { stavbaId: stavba_id }
+                    else
+                      { castObceKod: cast_obce_kod, typStavbyKod: typ_stavby_kod, cisloDomovni: cislo_domovni }
+                    end
+          message[:format] = format
+          message.merge!(options)
+
+          call_operation(:generuj_info_o_stavbach, message)
+        end
+        alias generate_building_info generuj_info_o_stavbach
+
+        def generuj_info_o_jednotkach(jednotka_id:, format: 'pdf', **options)
+          validate_format!(format)
+          message = { jednotkaId: jednotka_id, format: format }.merge(options)
+
+          call_operation(:generuj_info_o_jednotkach, message)
+        end
+        alias generate_unit_info generuj_info_o_jednotkach
+
+        def generuj_prehled_vlastnictvi(opravneny_subjekt_id:, format: 'pdf', **options)
+          validate_format!(format)
+          message = { opravnenySubjektId: opravneny_subjekt_id, format: format }.merge(options)
+
+          call_operation(:generuj_prehled_vlastnictvi, message)
+        end
+        alias generate_ownership_overview generuj_prehled_vlastnictvi
+
+        def generuj_cenove_udaje_dle_nemovitosti(nemovitost_id:, format: 'pdf', **options)
+          validate_format!(format)
+          message = { nemovitostId: nemovitost_id, format: format }.merge(options)
+
+          call_operation(:generuj_cenove_udaje_dle_nemovitosti, message)
+        end
+        alias generate_price_by_property generuj_cenove_udaje_dle_nemovitosti
+
+        # --- Report management ---
+
+        def seznam_sestav(id_sestavy: nil)
+          message = {}
+          message[:idSestavy] = id_sestavy if id_sestavy
+          call_operation(:seznam_sestav, message)
+        end
+        alias list_reports seznam_sestav
+
+        def vrat_sestavu(id_sestavy:)
+          call_operation(:vrat_sestavu, { idSestavy: id_sestavy })
+        end
+        alias download_report vrat_sestavu
+
+        def smaz_sestavu(id_sestavy:)
+          call_operation(:smaz_sestavu, { idSestavy: id_sestavy })
+        end
+        alias delete_report smaz_sestavu
+
+        private
+
+        def service_name
+          :sestavy
+        end
+
+        def validate_format!(format)
+          return if VALID_FORMATS.include?(format.to_s.downcase)
+
+          raise ArgumentError, "Invalid format: #{format}. Valid formats: #{VALID_FORMATS.join(', ')}"
+        end
+      end
+    end
+  end
+end

data/lib/cuzk/soap/services/search_service.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    module Services
+      class SearchService < BaseService
+        # Find parcel by parcelaId OR katastrUzemiKod + kmenoveCislo + optional poddeleni
+        def najdi_parcelu(katastr_uzemi_kod: nil, kmenove_cislo: nil, parcela_id: nil, **options)
+          message = if parcela_id
+                      { parcelaId: parcela_id }
+                    else
+                      { katastrUzemiKod: katastr_uzemi_kod, kmenoveCislo: kmenove_cislo }
+                    end
+          message.merge!(options)
+
+          call_operation(:najdi_parcelu, message)
+        end
+        alias search_parcel najdi_parcelu
+
+        # Find building by stavbaId OR castObceKod + typStavbyKod + cisloDomovni
+        def najdi_stavbu(stavba_id: nil, cast_obce_kod: nil, typ_stavby_kod: nil, cislo_domovni: nil, **options)
+          message = if stavba_id
+                      { stavbaId: stavba_id }
+                    else
+                      {
+                        castObceKod: cast_obce_kod,
+                        typStavbyKod: typ_stavby_kod,
+                        cisloDomovni: cislo_domovni
+                      }
+                    end
+          message.merge!(options)
+
+          call_operation(:najdi_stavbu, message)
+        end
+        alias search_building najdi_stavbu
+
+        def najdi_jednotku(katastr_uzemi_kod: nil, cislo_jednotky: nil, jednotka_id: nil, **options)
+          message = if jednotka_id
+                      { jednotkaId: jednotka_id }
+                    else
+                      { katastrUzemiKod: katastr_uzemi_kod, cisloJednotky: cislo_jednotky }
+                    end
+          message.merge!(options)
+
+          call_operation(:najdi_jednotku, message)
+        end
+        alias search_unit najdi_jednotku
+
+        # Find person/entity: by ico/nazev (legal) or jmeno/prijmeni (natural)
+        def najdi_os(**params)
+          message = {}
+          message[:ico] = params[:ico] if params[:ico]
+          message[:nazev] = params[:nazev] if params[:nazev]
+          message[:jmeno] = params[:jmeno] if params[:jmeno]
+          message[:prijmeni] = params[:prijmeni] if params[:prijmeni]
+          message[:rc] = params[:rc] if params[:rc]
+          message[:datumNarozeni] = params[:datum_narozeni] if params[:datum_narozeni]
+          message[:datumK] = params[:datum_k] if params[:datum_k]
+
+          call_operation(:najdi_os, message)
+        end
+        alias search_subject najdi_os
+
+        def najdi_pravo_stavby(**options)
+          call_operation(:najdi_pravo_stavby, options)
+        end
+        alias search_building_right najdi_pravo_stavby
+
+        def najdi_rizeni(**options)
+          call_operation(:najdi_rizeni, options)
+        end
+        alias search_proceedings najdi_rizeni
+
+        def stav_ws
+          call_operation(:stav_ws, {})
+        end
+        alias service_status stav_ws
+
+        private
+
+        def service_name
+          :vyhledat
+        end
+      end
+    end
+  end
+end

data/lib/cuzk/soap/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    VERSION = '0.1.0'
+  end
+end

data/lib/cuzk/soap/wsdl_manager.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    class WSDLManager
+      WSDL_FILES = {
+        v31: {
+          vyhledat: 'vyhledat_v3_1.wsdl',
+          sestavy: 'sestavy_v3_1.wsdl',
+          informace: 'informace_v3_1.wsdl',
+          ciselnik: 'ciselnik_v3_1.wsdl',
+          ucet: 'ucet_v3_1.wsdl'
+        },
+        v29: {
+          vyhledat: 'vyhledat_v29.wsdl',
+          sestavy: 'sestavy_v29.wsdl',
+          informace: 'informace_v29.wsdl',
+          ciselnik: 'ciselnik_v29.wsdl',
+          ucet: 'ucet_v29.wsdl'
+        }
+      }.freeze
+
+      # v3.1 uses URN-style type namespaces (distinct from service namespaces)
+      WSDP_TYPE_NAMESPACES = {
+        v31: {
+          vyhledat: 'urn:cz:gov:cuzk:iskn:types:wsdp:vyhledat:3.1',
+          sestavy: 'urn:cz:gov:cuzk:iskn:types:wsdp:sestavy:3.1',
+          informace: 'urn:cz:gov:cuzk:iskn:types:wsdp:informace:3.1',
+          ciselnik: 'urn:cz:gov:cuzk:iskn:types:wsdp:ciselnik:3.1',
+          ucet: 'urn:cz:gov:cuzk:iskn:types:wsdp:ucet:3.1'
+        },
+        v29: {
+          vyhledat: 'http://katastr.cuzk.cz/vyhledat/types/v2.9',
+          sestavy: 'http://katastr.cuzk.cz/sestavy/types/v2.9',
+          informace: 'http://katastr.cuzk.cz/informace/types/v2.9',
+          ciselnik: 'http://katastr.cuzk.cz/ciselnik/types/v2.9',
+          ucet: 'http://katastr.cuzk.cz/ucet/types/v2.9'
+        }
+      }.freeze
+
+      # v3.1 uses URN-style namespaces per service
+      WSDP_SERVICE_NAMESPACES = {
+        v31: {
+          vyhledat: 'urn:cz:gov:cuzk:iskn:services:wsdp:vyhledat:3.1',
+          sestavy: 'urn:cz:gov:cuzk:iskn:services:wsdp:sestavy:3.1',
+          informace: 'urn:cz:gov:cuzk:iskn:services:wsdp:informace:3.1',
+          ciselnik: 'urn:cz:gov:cuzk:iskn:services:wsdp:ciselnik:3.1',
+          ucet: 'urn:cz:gov:cuzk:iskn:services:wsdp:ucet:3.1'
+        },
+        v29: {
+          vyhledat: 'http://katastr.cuzk.cz/vyhledat/v2.9',
+          sestavy: 'http://katastr.cuzk.cz/sestavy/v2.9',
+          informace: 'http://katastr.cuzk.cz/informace/v2.9',
+          ciselnik: 'http://katastr.cuzk.cz/ciselnik/v2.9',
+          ucet: 'http://katastr.cuzk.cz/ucet/v2.9'
+        }
+      }.freeze
+
+      # WSDL directory paths differ between versions
+      WSDL_DIR_PATHS = {
+        v31: 'ws3_1/wsdp/',
+        v29: 'ws29/wsdp/'
+      }.freeze
+
+      # SOAP endpoints follow a different path pattern
+      SOAP_ENDPOINT_PATHS = {
+        v31: 'ws/wsdp/3.1/',
+        v29: 'ws/wsdp/2.9/'
+      }.freeze
+
+      TRIAL_BASE_URL = 'https://wsdptrial.cuzk.gov.cz/trial/'
+      PRODUCTION_BASE_URL = 'https://katastr.cuzk.gov.cz/'
+
+      attr_reader :version, :environment
+
+      def initialize(version: :v31, environment: :production)
+        @version = version
+        @environment = environment
+      end
+
+      def wsdl_url(service)
+        filename = wsdl_files.fetch(service) do
+          raise ArgumentError, "Unknown service: #{service}. Available: #{available_services.join(', ')}"
+        end
+
+        "#{documentation_base_url}#{wsdl_dir_path}#{filename}"
+      end
+
+      def soap_endpoint_url(service)
+        unless wsdl_files.key?(service)
+          raise ArgumentError, "Unknown service: #{service}. Available: #{available_services.join(', ')}"
+        end
+
+        "#{base_url}#{soap_endpoint_path}#{service}"
+      end
+
+      def namespace(service)
+        namespaces = WSDP_SERVICE_NAMESPACES.fetch(@version) do
+          raise ConfigurationError, "Unknown WSDP version: #{@version}"
+        end
+
+        namespaces.fetch(service) do
+          raise ArgumentError, "Unknown service: #{service}"
+        end
+      end
+
+      def types_namespace(service)
+        type_namespaces = WSDP_TYPE_NAMESPACES.fetch(@version) do
+          raise ConfigurationError, "Unknown WSDP version: #{@version}"
+        end
+
+        type_namespaces.fetch(service) do
+          raise ArgumentError, "Unknown service: #{service}"
+        end
+      end
+
+      def soap_action(service, operation)
+        ns = namespace(service)
+        if @version == :v31
+          # v3.1 uses urn-style: urn:cz:gov:cuzk:iskn:services:wsdp:{service}:{operation}
+          base = ns.sub(/:[\d.]+\z/, '')
+          "#{base}:#{operation}"
+        else
+          # v2.9 uses http-style: http://katastr.cuzk.cz/{service}/{operation}
+          base = ns.sub(%r{/v[\d.]+\z}, '')
+          "#{base}/#{operation}"
+        end
+      end
+
+      def available_services
+        wsdl_files.keys
+      end
+
+      def service_available?(service)
+        wsdl_files.key?(service)
+      end
+
+      def all_wsdl_urls
+        wsdl_files.transform_values { |filename| "#{documentation_base_url}#{wsdl_dir_path}#{filename}" }
+      end
+
+      def all_soap_endpoints
+        wsdl_files.keys.to_h { |service| [service, soap_endpoint_url(service)] }
+      end
+
+      private
+
+      def wsdl_files
+        WSDL_FILES.fetch(@version) do
+          raise ConfigurationError, "Unknown WSDP version: #{@version}. Available: #{WSDL_FILES.keys.join(', ')}"
+        end
+      end
+
+      def wsdl_dir_path
+        WSDL_DIR_PATHS.fetch(@version)
+      end
+
+      def soap_endpoint_path
+        SOAP_ENDPOINT_PATHS.fetch(@version)
+      end
+
+      def base_url
+        @environment == :testing ? TRIAL_BASE_URL : PRODUCTION_BASE_URL
+      end
+
+      def documentation_base_url
+        "#{base_url}dokumentace/"
+      end
+    end
+  end
+end