cuzk-soap 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 854f7991c5000a7bf1e10e0c83e117cd945be2962da139dad760fe9f408dd612
+  data.tar.gz: d71c566236109548a142e35e456a5bd7a4443ceed4f3b1e1b8f09e81bd756124
+SHA512:
+  metadata.gz: d473c1d48115563b9f53917c52976878f2581dfe591b7d3f9b304bde01bf25cf65d2d04f2740143fd84aecfb95d04cf9736bbb3ab278b09d233f77c709d5f143
+  data.tar.gz: f4e484e612eb98dcb7d4b5e37027ff01c06e21da225ad96066e3cb59113a1ec658ea17edb2a2367b47c063750389b15b1313c6214775e562e56bacde35f1768f

data/README.md

@@ -0,0 +1,311 @@
+# CUZK::SOAP
+
+Ruby client for the ČÚZK WSDP SOAP API (Czech Cadastral Registry / Český úřad zeměměřický a katastrální).
+
+Wraps the [WSDP (Webové služby dálkového přístupu)](https://www.cuzk.gov.cz/Katastr-nemovitosti/Poskytovani-udaju-z-KN/Dalkovypristup/Webove-sluzby-dalkoveho-pristupu.aspx) v3.1 and v2.9 services with a Ruby-friendly interface, including cost tracking, batch processing, and circuit breaker resilience.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'cuzk-soap'
+```
+
+Then run `bundle install`. Requires Ruby >= 3.2.0.
+
+## Configuration
+
+### Global configuration
+
+```ruby
+CUZK::SOAP.configure do |c|
+  c.username    = 'YOUR_WSDP_USERNAME'
+  c.password    = 'YOUR_WSDP_PASSWORD'
+  c.environment = :production          # :production or :testing
+  c.wsdp_version = :v31               # :v31 (default) or :v29
+
+  # Optional: cost management (CZK)
+  c.daily_budget_limit  = 1000.0
+  c.monthly_budget_limit = 15_000.0
+  c.auto_pause_on_budget_exceeded = true
+
+  # Optional: timeouts
+  c.open_timeout = 30
+  c.read_timeout = 120
+
+  # Optional: SSL verification (set :none for trial environment)
+  c.ssl_verify_mode = :peer
+end
+```
+
+### Per-client configuration
+
+You can also pass credentials and options directly when creating a client. These override the global configuration:
+
+```ruby
+client = CUZK::SOAP::Client.new(
+  username: 'YOUR_WSDP_USERNAME',
+  password: 'YOUR_WSDP_PASSWORD',
+  environment: :testing,
+  daily_budget_limit: 500.0
+)
+```
+
+## Usage
+
+### Search operations (`vyhledat` service)
+
+Search for parcels, buildings, units, and subjects in the cadastral registry.
+
+```ruby
+client = CUZK::SOAP::Client.new(
+  username: 'WSTEST', password: 'WSHESLO', environment: :testing
+)
+
+# Search parcel by cadastral unit code + parcel number
+result = client.search_parcel(
+  cadastral_unit_code: '691232',
+  parcel_number: '68'
+)
+
+# Search parcel by internal ID
+result = client.search_parcel(parcel_id: '12345')
+
+# Search building by composite key
+result = client.search_building(
+  district_part_code: '691232',
+  building_type_code: '1',
+  building_number: '50'
+)
+
+# Search building by internal ID
+result = client.search_building(building_id: '999')
+
+# Search unit
+result = client.search_unit(
+  cadastral_unit_code: '691232',
+  unit_number: '10'
+)
+
+# Search subject (natural person)
+result = client.search_subject(jmeno: 'Jan', prijmeni: 'Novak')
+
+# Search subject (legal entity by IČO)
+result = client.search_subject(ico: '12345678')
+```
+
+### Report generation (`sestavy` service)
+
+Report generation is **asynchronous**. You request generation, poll for completion, then download.
+
+```ruby
+# 1. Request LV (list vlastnictví) generation
+result = client.generate_lv(lv_id: '1234', format: 'pdf')
+
+# 2. Poll for status
+reports = client.list_reports
+
+# 3. Download when ready
+report = client.download_report(id_sestavy: '42')
+
+# 4. Clean up
+client.delete_report(id_sestavy: '42')
+```
+
+Other report types:
+
+```ruby
+# Parcel info report
+client.generate_parcel_info(
+  katastr_uzemi_kod: '691232',
+  kmenove_cislo: '68',
+  format: 'pdf'
+)
+
+# Building info report
+client.generate_building_info(
+  stavba_id: '999',
+  format: 'pdf'
+)
+
+# Unit info report
+client.generate_unit_info(jednotka_id: '555', format: 'pdf')
+
+# Ownership overview
+client.report_service.generuj_prehled_vlastnictvi(
+  opravneny_subjekt_id: '999',
+  format: 'pdf'
+)
+
+# Price data by property
+client.report_service.generuj_cenove_udaje_dle_nemovitosti(
+  nemovitost_id: '123',
+  format: 'pdf'
+)
+```
+
+Supported formats: `pdf`, `xml`, `html`, `zip`.
+
+### Codelist operations (`ciselnik` service)
+
+```ruby
+# List all cadastral units
+units = client.list_cadastral_units
+```
+
+### Subject info (`informace` service)
+
+```ruby
+# Read subject details by ID
+subject = client.informace_service.cti_os(opravneny_subjekt_id: '999')
+```
+
+### Account management (`ucet` service)
+
+```ruby
+# Check account status / connectivity
+status = client.account_status
+
+# Change password
+client.change_password(
+  old_password: 'OLD_PASSWORD',
+  new_password: 'NEW_PASSWORD'
+)
+```
+
+### Batch processing
+
+Execute multiple operations in sequence with progress tracking:
+
+```ruby
+operations = [
+  { method: :search_parcel, params: { cadastral_unit_code: '691232', parcel_number: '68' } },
+  { method: :search_parcel, params: { cadastral_unit_code: '691232', parcel_number: '69' } },
+  { method: :generate_lv,   params: { lv_id: '1234' } }
+]
+
+processor = client.batch_generate(operations) do |current, total, job_id|
+  puts "#{job_id}: #{current}/#{total}"
+end
+
+puts processor.summary
+# => { job_id: "batch_...", status: :completed, total_operations: 3, successful: 3, failed: 0, progress: 100.0 }
+```
+
+### Cost management
+
+The built-in cost manager tracks spending against ČÚZK fee schedules:
+
+```ruby
+# Get cost estimate before running operations
+estimate = client.cost_estimate(lv_extract_pdf: 5, property_info: 10)
+# => 550.0 (CZK)
+
+# Check remaining budget
+status = client.service_status
+status[:cost_manager][:daily_remaining]   # => 450.0
+status[:cost_manager][:monthly_remaining] # => 14450.0
+status[:cost_manager][:budget_alert]      # => false
+```
+
+When `auto_pause_on_budget_exceeded` is enabled, paid operations raise `CUZK::SOAP::CostLimitExceededError` if the estimated cost would exceed the daily or monthly budget.
+
+### Direct service access
+
+For operations not exposed through the `Client` convenience methods, access services directly. All Czech method names are available alongside English aliases:
+
+```ruby
+# Czech names
+client.search_service.najdi_parcelu(katastr_uzemi_kod: '691232', kmenove_cislo: '68')
+client.search_service.najdi_stavbu(stavba_id: '999')
+client.search_service.najdi_os(ico: '12345678')
+client.search_service.najdi_rizeni(...)
+client.report_service.generuj_lv(lv_id: '1234')
+
+# English aliases
+client.search_service.search_parcel(...)
+client.search_service.search_building(...)
+client.search_service.search_subject(...)
+client.search_service.search_proceedings(...)
+client.report_service.generate_lv(...)
+```
+
+### Monitoring
+
+```ruby
+# Full service status with cost tracking
+client.service_status
+# => { environment: :testing, wsdp_version: :v31, connected: true, cost_manager: { ... } }
+
+# WSDP version info with available services and endpoints
+client.wsdp_version_info
+# => { version: :v31, available_services: [:vyhledat, :sestavy, ...], wsdl_urls: { ... }, soap_endpoints: { ... } }
+```
+
+## WSDP Services
+
+| Service     | Description                        | Client accessor         |
+|-------------|------------------------------------|-------------------------|
+| `vyhledat`  | Search parcels, buildings, units, subjects | `client.search_service`  |
+| `sestavy`   | Generate & manage reports (async)  | `client.report_service`  |
+| `informace` | Read subject detail data           | `client.informace_service` |
+| `ciselnik`  | Codelists (cadastral units, etc.)  | `client.ciselnik_service` |
+| `ucet`      | Account status & password change   | `client.account_service` |
+
+## Error handling
+
+```ruby
+begin
+  client.search_parcel(cadastral_unit_code: '691232', parcel_number: '68')
+rescue CUZK::SOAP::AuthenticationError => e
+  # Invalid credentials or expired session
+rescue CUZK::SOAP::NetworkTimeoutError => e
+  # Connection timeout
+rescue CUZK::SOAP::CostLimitExceededError => e
+  # Budget limit would be exceeded
+rescue CUZK::SOAP::WSDPError => e
+  # WSDP service fault
+  e.fault_code    # SOAP fault code
+  e.fault_string  # SOAP fault description
+rescue CUZK::SOAP::Error => e
+  # Base error class for all gem errors
+end
+```
+
+## Trial environment
+
+ČÚZK provides a trial environment for development and testing with pre-loaded test data (Prachatice district):
+
+| Account       | Username   | Password   |
+|---------------|------------|------------|
+| Standard      | `WSTEST`   | `WSHESLO`  |
+| Free          | `WSTESTB`  | `WSHESLOB` |
+| Verification  | `WSTESTO`  | `WSHESLOO` |
+| CzechPoint    | `WSTESTC`  | `WSHESLOC` |
+
+```ruby
+client = CUZK::SOAP::Client.new(
+  username: 'WSTEST',
+  password: 'WSHESLO',
+  environment: :testing,
+  ssl_verify_mode: :none  # trial environment may have CRL issues
+)
+```
+
+## Development
+
+```bash
+bin/setup                        # Install dependencies
+bundle exec rspec spec/cuzk      # Run unit tests (178 examples)
+bundle exec rspec spec/integration # Run integration tests against VCR cassettes
+bundle exec rspec spec/           # Run all tests (194 examples)
+bundle exec rubocop              # Run linter
+
+# Re-record VCR cassettes against the live trial environment
+VCR_RECORD=new_episodes bundle exec rspec spec/integration/
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/cuzk/soap/authentication/test_credentials.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    module Authentication
+      class TestCredentials < WSDPCredentials
+        TEST_USERNAME = 'WSTEST'
+        TEST_PASSWORD = 'WSHESLO'
+
+        # Additional trial accounts
+        ACCOUNTS = {
+          standard: { username: 'WSTEST', password: 'WSHESLO' },
+          free: { username: 'WSTESTB', password: 'WSHESLOB' },
+          verification: { username: 'WSTESTO', password: 'WSHESLOO' },
+          czechpoint: { username: 'WSTESTC', password: 'WSHESLOC' }
+        }.freeze
+
+        def initialize(account: :standard)
+          creds = ACCOUNTS.fetch(account) do
+            raise ArgumentError, "Unknown test account: #{account}. Available: #{ACCOUNTS.keys.join(', ')}"
+          end
+
+          super(
+            username: creds[:username],
+            password: creds[:password],
+            environment: :testing
+          )
+        end
+      end
+    end
+  end
+end

data/lib/cuzk/soap/authentication/wsdp_credentials.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'digest'
+require 'base64'
+require 'time'
+
+module CUZK
+  module SOAP
+    module Authentication
+      class WSDPCredentials
+        WSSE_NAMESPACE = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
+        WSU_NAMESPACE = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'
+        PASSWORD_TEXT_TYPE =
+          'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'
+
+        attr_reader :username, :environment
+
+        def initialize(username:, password:, environment: :production)
+          @username = username
+          @password = password
+          @environment = environment
+        end
+
+        # Build the WS-Security header hash for Savon's :soap_header option.
+        # WSDP requires PasswordText over HTTPS (not digest).
+        def wsse_security_header
+          {
+            'wsse:Security' => {
+              '@xmlns:wsse' => WSSE_NAMESPACE,
+              '@xmlns:wsu' => WSU_NAMESPACE,
+              '@SOAP-ENV:mustUnderstand' => '1',
+              'wsse:UsernameToken' => {
+                'wsse:Username' => @username,
+                'wsse:Password' => {
+                  '@Type' => PASSWORD_TEXT_TYPE,
+                  :content! => @password
+                }
+              }
+            }
+          }
+        end
+
+        # Savon wsse_auth array: [username, password] for PasswordText
+        # Savon uses plaintext by default, :digest flag enables digest mode.
+        def savon_wsse_auth
+          [@username, @password]
+        end
+
+        def validate_credentials
+          !@username.nil? && !@username.empty? &&
+            !@password.nil? && !@password.empty?
+        end
+      end
+    end
+  end
+end

data/lib/cuzk/soap/batch_processor.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    class BatchProcessor
+      attr_reader :job_id, :status, :operations, :results, :errors
+
+      def initialize(client, operations)
+        @client = client
+        @operations = operations
+        @job_id = generate_job_id
+        @status = :pending
+        @results = []
+        @errors = []
+        @progress_callbacks = []
+        @completion_callbacks = []
+        @error_callbacks = []
+      end
+
+      def start
+        @status = :running
+        total = @operations.size
+
+        @operations.each_with_index do |operation, index|
+          break if @status == :cancelled
+
+          execute_operation(operation, index)
+          notify_progress(index + 1, total)
+        end
+
+        @status = @errors.empty? ? :completed : :completed_with_errors
+        notify_completion
+        self
+      rescue StandardError => e
+        @status = :failed
+        raise BatchProcessingError, "Batch job #{@job_id} failed: #{e.message}"
+      end
+
+      def cancel
+        @status = :cancelled
+      end
+
+      def progress_percentage
+        return 0 if @operations.empty?
+
+        completed = @results.size + @errors.size
+        (completed.to_f / @operations.size * 100).round(1)
+      end
+
+      def successful_count
+        @results.size
+      end
+
+      def failed_count
+        @errors.size
+      end
+
+      def on_progress(&callback)
+        @progress_callbacks << callback
+      end
+
+      def on_completion(&callback)
+        @completion_callbacks << callback
+      end
+
+      def on_error(&callback)
+        @error_callbacks << callback
+      end
+
+      def summary
+        {
+          job_id: @job_id,
+          status: @status,
+          total_operations: @operations.size,
+          successful: successful_count,
+          failed: failed_count,
+          progress: progress_percentage
+        }
+      end
+
+      private
+
+      def execute_operation(operation, index)
+        method_name = operation[:method]
+        params = operation[:params] || {}
+
+        result = @client.public_send(method_name, **params)
+        @results << { index: index, operation: operation, result: result }
+      rescue Error => e
+        error_entry = { index: index, operation: operation, error: e }
+        @errors << error_entry
+        notify_error(error_entry)
+      end
+
+      def notify_progress(current, total)
+        @progress_callbacks.each { |cb| cb.call(current, total, @job_id) }
+      end
+
+      def notify_completion
+        @completion_callbacks.each { |cb| cb.call(summary) }
+      end
+
+      def notify_error(error_entry)
+        @error_callbacks.each { |cb| cb.call(error_entry) }
+      end
+
+      def generate_job_id
+        "batch_#{Time.now.utc.strftime('%Y%m%d%H%M%S')}_#{SecureRandom.hex(4)}"
+      end
+    end
+  end
+end

data/lib/cuzk/soap/change_tracker.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module CUZK
+  module SOAP
+    class ChangeTracker
+      attr_reader :tracked_properties, :last_check, :changes_detected
+
+      def initialize(client)
+        @client = client
+        @tracked_properties = {}
+        @last_check = nil
+        @changes_detected = []
+        @alert_callbacks = []
+      end
+
+      def add_property(property_id, property_type:, monitoring_level: :standard, **metadata)
+        @tracked_properties[property_id] = {
+          property_type: property_type,
+          monitoring_level: monitoring_level,
+          added_at: Time.now.utc,
+          last_snapshot: nil,
+          metadata: metadata
+        }
+      end
+
+      def remove_property(property_id)
+        @tracked_properties.delete(property_id)
+      end
+
+      def check_for_changes
+        changes = []
+
+        @tracked_properties.each do |property_id, tracking_info|
+          current_data = fetch_current_data(property_id, tracking_info)
+          previous_data = tracking_info[:last_snapshot]
+
+          if previous_data && current_data != previous_data
+            change = {
+              property_id: property_id,
+              property_type: tracking_info[:property_type],
+              detected_at: Time.now.utc,
+              previous_data: previous_data,
+              current_data: current_data
+            }
+            changes << change
+          end
+
+          tracking_info[:last_snapshot] = current_data
+        end
+
+        @last_check = Time.now.utc
+        @changes_detected.concat(changes)
+        trigger_alerts(changes) unless changes.empty?
+        changes
+      end
+
+      def changes_since(date)
+        @changes_detected.select { |c| c[:detected_at] >= date }
+      end
+
+      def change_history(property_id)
+        @changes_detected.select { |c| c[:property_id] == property_id }
+      end
+
+      def on_change(&callback)
+        @alert_callbacks << callback
+      end
+
+      def summary
+        {
+          tracked_count: @tracked_properties.size,
+          total_changes: @changes_detected.size,
+          last_check: @last_check
+        }
+      end
+
+      private
+
+      def fetch_current_data(property_id, tracking_info)
+        case tracking_info[:property_type]
+        when :parcel
+          parts = property_id.split('/')
+          @client.report_service.informace_o_parcele(
+            katastr_uzemi_kod: parts[0],
+            kmenove_cislo: parts[1],
+            format: 'xml'
+          )
+        when :building
+          parts = property_id.split('/')
+          @client.report_service.informace_o_budove(
+            katastr_uzemi_kod: parts[0],
+            cislo_budovy: parts[1],
+            format: 'xml'
+          )
+        when :unit
+          @client.report_service.informace_o_jednotce(
+            jednotka_id: property_id,
+            format: 'xml'
+          )
+        else
+          raise ArgumentError, "Unknown property type: #{tracking_info[:property_type]}"
+        end
+      end
+
+      def trigger_alerts(changes)
+        @alert_callbacks.each { |cb| cb.call(changes) }
+      end
+    end
+  end
+end