cuzk-rest 0.1.0

data/lib/cuzk/rest/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module CUZK
+  module REST
+    class Configuration
+      DEFAULTS = {
+        base_url: 'https://api-kn.cuzk.gov.cz',
+        api_version: 'v1',
+        timeout: 30,
+        open_timeout: 10,
+        retries: 3,
+        retry_interval: 0.5,
+        requests_per_minute: 60,
+        burst_limit: 10,
+        cache_ttl: 86_400, # 24 hours in seconds
+        enable_caching: false,
+        log_requests: false,
+        log_responses: false,
+        privacy_mode: :strict,
+        mask_personal_data: true
+      }.freeze
+
+      attr_accessor :api_key, :base_url, :api_version,
+                    :timeout, :open_timeout,
+                    :retries, :retry_interval,
+                    :requests_per_minute, :burst_limit,
+                    :cache_store, :cache_ttl, :enable_caching,
+                    :logger, :log_requests, :log_responses,
+                    :privacy_mode, :mask_personal_data,
+                    :user_agent
+
+      def initialize
+        DEFAULTS.each { |key, value| public_send(:"#{key}=", value) }
+        @api_key = ENV.fetch('CUZK_REST_API_KEY', nil)
+        @user_agent = "cuzk-rest/#{CUZK::REST::VERSION} Ruby/#{RUBY_VERSION}"
+      end
+
+      def api_url
+        "#{base_url}/api/#{api_version}"
+      end
+
+      def validate!
+        raise ConfigurationError, 'api_key is required' if api_key.nil? || api_key.empty?
+        raise ConfigurationError, 'base_url is required' if base_url.nil? || base_url.empty?
+
+        true
+      end
+    end
+  end
+end

data/lib/cuzk/rest/connection.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module CUZK
+  module REST
+    class Connection
+      attr_reader :config, :last_response_metadata
+
+      def initialize(config = nil)
+        @config = config || CUZK::REST.configuration
+        @config.validate!
+        @rate_limiter = RateLimiter.new(
+          requests_per_minute: @config.requests_per_minute,
+          burst_limit: @config.burst_limit
+        )
+        @last_response_metadata = {}
+      end
+
+      def get(path, params = {})
+        request(:get, path, params)
+      end
+
+      def post(path, body = {})
+        request(:post, path, body)
+      end
+
+      private
+
+      def request(method, path, payload = {})
+        @rate_limiter.throttle!
+
+        response = connection.public_send(method, path) do |req|
+          case method
+          when :get
+            req.params.update(payload) unless payload.empty?
+          when :post
+            req.body = Oj.dump(payload, mode: :compat) unless payload.empty?
+          end
+        end
+
+        handle_response(response)
+      rescue Faraday::TimeoutError, ::Timeout::Error => e
+        raise TimeoutError.new("Request timed out: #{e.message}", original_error: e)
+      rescue Faraday::ConnectionFailed => e
+        if e.message.include?('execution expired') || e.message.include?('timed out') || e.cause.is_a?(::Timeout::Error)
+          raise TimeoutError.new("Request timed out: #{e.message}", original_error: e)
+        end
+
+        raise ConnectionError.new("Connection failed: #{e.message}", original_error: e)
+      rescue Faraday::RetriableResponse => e
+        handle_response(e.response)
+      rescue Faraday::Error => e
+        raise NetworkError.new("Network error: #{e.message}", original_error: e)
+      end
+
+      def connection
+        @connection ||= Faraday.new(url: config.api_url) do |f|
+          f.headers['Accept'] = 'application/json'
+          f.headers['Content-Type'] = 'application/json'
+          f.headers['User-Agent'] = config.user_agent
+          f.headers['Accept-Language'] = 'cs-CZ'
+          f.headers['ApiKey'] = config.api_key if config.api_key
+
+          if config.retries.positive?
+            f.request :retry, max: config.retries,
+                              interval: config.retry_interval,
+                              retry_statuses: [429, 500, 502, 503, 504],
+                              methods: %i[get],
+                              exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed]
+          end
+
+          f.options.timeout = config.timeout
+          f.options.open_timeout = config.open_timeout
+
+          f.response :logger, config.logger, bodies: config.log_responses if config.logger && config.log_requests
+
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def handle_response(response)
+        body = response.respond_to?(:body) ? response.body : response[:body]
+        status = response.respond_to?(:status) ? response.status : response[:status]
+
+        case status
+        when 200..299
+          parse_body(body)
+        when 401
+          raise AuthenticationError.new('Authentication failed', status: status, response_body: body)
+        when 403
+          raise AuthorizationError.new('Access forbidden', status: status, response_body: body)
+        when 404
+          raise NotFoundError.new('Resource not found', status: status, response_body: body)
+        when 422
+          raise ValidationError.new('Validation failed', status: status, response_body: body)
+        when 429
+          raise RateLimitedError.new('Rate limit exceeded', status: status, response_body: body)
+        when 400..499
+          raise APIError.new("Client error (#{status})", status: status, response_body: body)
+        when 500..599
+          raise ServerError.new("Server error (#{status})", status: status, response_body: body)
+        else
+          raise InvalidResponseError, "Unexpected response status: #{status}"
+        end
+      end
+
+      def parse_body(body)
+        return nil if body.nil? || body.empty?
+
+        parsed = Oj.load(body, mode: :compat, symbol_keys: false)
+        unwrap_response(parsed)
+      rescue EncodingError, Oj::ParseError, Oj::Error => e
+        raise ParsingError.new("Failed to parse response: #{e.message}", original_error: e)
+      end
+
+      def unwrap_response(parsed)
+        if wrapped_response?(parsed)
+          @last_response_metadata = parsed.except('data')
+          parsed['data']
+        else
+          @last_response_metadata = {}
+          parsed
+        end
+      end
+
+      def wrapped_response?(parsed)
+        parsed.is_a?(Hash) && parsed.key?('data') &&
+          (parsed.key?('zpravy') || parsed.key?('provedenoVolani') || parsed.key?('aktualnostDatK'))
+      end
+    end
+  end
+end

data/lib/cuzk/rest/errors.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module CUZK
+  module REST
+    # Base error for all CUZK REST errors
+    class Error < StandardError
+      attr_reader :original_error
+
+      def initialize(message = nil, original_error: nil)
+        @original_error = original_error
+        super(message)
+      end
+    end
+
+    # Configuration errors
+    class ConfigurationError < Error; end
+
+    # API errors (HTTP response errors)
+    class APIError < Error
+      attr_reader :status, :response_body
+
+      def initialize(message = nil, status: nil, response_body: nil, **kwargs)
+        @status = status
+        @response_body = response_body
+        super(message, **kwargs)
+      end
+    end
+
+    class AuthenticationError < APIError; end
+    class AuthorizationError < APIError; end
+    class NotFoundError < APIError; end
+    class ValidationError < APIError; end
+    class RateLimitedError < APIError; end
+    class ServerError < APIError; end
+
+    # Network errors
+    class NetworkError < Error; end
+    class TimeoutError < NetworkError; end
+    class ConnectionError < NetworkError; end
+
+    # Data errors
+    class DataError < Error; end
+    class ParsingError < DataError; end
+    class InvalidResponseError < DataError; end
+
+    # Privacy & compliance errors
+    class PrivacyError < Error; end
+    class GDPRViolationError < PrivacyError; end
+  end
+end

data/lib/cuzk/rest/rate_limiter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CUZK
+  module REST
+    class RateLimiter
+      def initialize(requests_per_minute: 60, burst_limit: 10)
+        @requests_per_minute = requests_per_minute
+        @burst_limit = burst_limit
+        @timestamps = []
+        @mutex = Mutex.new
+      end
+
+      def throttle!
+        @mutex.synchronize do
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          cleanup_old_timestamps(now)
+
+          if @timestamps.size >= @requests_per_minute
+            oldest = @timestamps.first
+            wait_time = 60.0 - (now - oldest)
+            sleep(wait_time) if wait_time.positive?
+            cleanup_old_timestamps(Process.clock_gettime(Process::CLOCK_MONOTONIC))
+          end
+
+          @timestamps << Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+
+      def requests_remaining
+        @mutex.synchronize do
+          cleanup_old_timestamps(Process.clock_gettime(Process::CLOCK_MONOTONIC))
+          @requests_per_minute - @timestamps.size
+        end
+      end
+
+      private
+
+      def cleanup_old_timestamps(now)
+        @timestamps.reject! { |ts| now - ts > 60.0 }
+      end
+    end
+  end
+end

data/lib/cuzk/rest/resource.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module CUZK
+  module REST
+    # Base class for all API resource objects.
+    # Provides common attribute handling and connection management.
+    class Resource
+      class << self
+        def connection
+          @connection || CUZK::REST::Client.default_connection
+        end
+
+        attr_writer :connection, :endpoint_path
+
+        def endpoint_path
+          @endpoint_path || raise(NotImplementedError, "#{name} must define endpoint_path")
+        end
+
+        private
+
+        def get(path, params = {})
+          connection.get("#{endpoint_path}#{path}", params)
+        end
+
+        def build(data)
+          new(data)
+        end
+
+        def build_collection(data, key: nil)
+          items = key ? data.fetch(key, []) : data
+          return [] unless items.is_a?(Array)
+
+          items.map { |item| build(item) }
+        end
+      end
+
+      attr_reader :attributes
+
+      def initialize(attributes = {})
+        @attributes = attributes.transform_keys(&:to_s)
+      end
+
+      def [](key)
+        @attributes[key.to_s]
+      end
+
+      def to_h
+        @attributes.dup
+      end
+
+      def inspect
+        "#<#{self.class.name} #{summary_attributes}>"
+      end
+
+      private
+
+      def summary_attributes
+        ''
+      end
+    end
+  end
+end

data/lib/cuzk/rest/resources/app_service.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module CUZK
+  module REST
+    module Resources
+      class AppService < Resource
+        self.endpoint_path = 'AplikacniSluzby'
+
+        def status
+          attributes['status']
+        end
+
+        def last_check
+          attributes['lastCheck']
+        end
+
+        def total_duration
+          attributes['totalDuration']
+        end
+
+        def entries
+          attributes['entries'] || []
+        end
+
+        class << self
+          def health
+            data = get('/Health')
+            build(data)
+          end
+
+          def account_status
+            data = get('/StavUctu')
+            build(data)
+          end
+
+          def data_currency
+            data = get('/AktualnostDat')
+            build(data)
+          end
+        end
+
+        private
+
+        def summary_attributes
+          "status=#{status}"
+        end
+      end
+    end
+  end
+end

data/lib/cuzk/rest/resources/building.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module CUZK
+  module REST
+    module Resources
+      class Building < Resource
+        self.endpoint_path = 'Stavby'
+
+        def id
+          attributes['id']
+        end
+
+        def descriptive_number
+          attributes['cisloPopisne']
+        end
+
+        def registration_number
+          attributes['cisloEvidencni']
+        end
+
+        def number
+          descriptive_number || registration_number
+        end
+
+        def number_type
+          if descriptive_number
+            :descriptive
+          elsif registration_number
+            :registration
+          end
+        end
+
+        def building_type
+          attributes['typStavby']
+        end
+
+        def building_type_code
+          attributes['kodTypuStavby']
+        end
+
+        def purpose
+          attributes['zpusobVyuziti']
+        end
+
+        def purpose_code
+          attributes['kodZpusobuVyuziti']
+        end
+
+        def cadastral_unit_code
+          attributes['kodKatastralnihoUzemi']
+        end
+
+        def cadastral_unit_name
+          attributes['nazevKatastralnihoUzemi']
+        end
+
+        def parcel_id
+          attributes['idParcely']
+        end
+
+        def lv_number
+          attributes['cisloLv']
+        end
+
+        def municipality
+          attributes['obec']
+        end
+
+        def municipality_part
+          attributes['castObce']
+        end
+
+        def street
+          attributes['ulice']
+        end
+
+        def house_number
+          attributes['cisloDomovni']
+        end
+
+        def postal_code
+          attributes['psc']
+        end
+
+        def full_address
+          parts = [street, house_number, municipality_part, municipality, postal_code].compact
+          parts.join(', ')
+        end
+
+        class << self
+          def find(id)
+            data = get("/#{id}")
+            build(data)
+          end
+
+          def search(params = {})
+            data = get('/Vyhledani', normalize_search_params(params))
+            build_collection(data, key: 'stavby')
+          end
+
+          def find_by_address_point(address_code)
+            data = get("/AdresniMisto/#{address_code}")
+            build(data)
+          end
+
+          private
+
+          def normalize_search_params(params)
+            mapping = {
+              municipality_part: 'KodCastiObce',
+              building_type: 'TypStavby',
+              house_number: 'CisloDomovni'
+            }
+
+            params.each_with_object({}) do |(key, value), result|
+              api_key = mapping[key] || key.to_s
+              result[api_key] = value
+            end
+          end
+        end
+
+        private
+
+        def summary_attributes
+          "id=#{id} number=#{number} type=#{number_type} municipality=#{municipality}"
+        end
+      end
+    end
+  end
+end

data/lib/cuzk/rest/resources/building_right.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module CUZK
+  module REST
+    module Resources
+      class BuildingRight < Resource
+        self.endpoint_path = 'PravaStavby'
+
+        def id
+          attributes['id']
+        end
+
+        def parcel_id
+          attributes['idParcely']
+        end
+
+        def building_id
+          attributes['idStavby']
+        end
+
+        def description
+          attributes['popis']
+        end
+
+        class << self
+          def find(id)
+            data = get("/#{id}")
+            build(data)
+          end
+
+          def find_by_parcel(parcel_id)
+            data = get("/Parcela/#{parcel_id}")
+            build_collection(data, key: 'pravaStavby')
+          end
+
+          def find_by_building(building_id)
+            data = get("/Stavba/#{building_id}")
+            build_collection(data, key: 'pravaStavby')
+          end
+        end
+
+        private
+
+        def summary_attributes
+          "id=#{id} parcel=#{parcel_id} building=#{building_id}"
+        end
+      end
+    end
+  end
+end

data/lib/cuzk/rest/resources/ownership.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module CUZK
+  module REST
+    module Resources
+      # Data model for ownership records. The ČÚZK REST API does not have a standalone
+      # ownership endpoint. Ownership data is embedded within other resources (parcels,
+      # buildings, units) via the LV (list vlastnictví) number.
+      class Ownership < Resource
+        def id
+          attributes['id']
+        end
+
+        def owner_name
+          if masked?
+            attributes['jmenoMaskovane'] || '[chráněno]'
+          else
+            attributes['jmeno']
+          end
+        end
+
+        def owner_type
+          attributes['typVlastnika']
+        end
+
+        def owner_type_code
+          attributes['kodTypuVlastnika']
+        end
+
+        def ownership_type
+          attributes['typVlastnictvi']
+        end
+
+        def ownership_type_code
+          attributes['kodTypuVlastnictvi']
+        end
+
+        def share_numerator
+          attributes['podilCitatel']
+        end
+
+        def share_denominator
+          attributes['podilJmenovatel']
+        end
+
+        def ownership_share
+          return nil unless share_numerator && share_denominator
+
+          "#{share_numerator}/#{share_denominator}"
+        end
+
+        def share_percentage
+          return nil unless share_numerator && share_denominator&.to_f&.positive?
+
+          (share_numerator.to_f / share_denominator * 100).round(2)
+        end
+
+        def property_id
+          attributes['idNemovitosti']
+        end
+
+        def property_type
+          attributes['typNemovitosti']
+        end
+
+        def lv_number
+          attributes['cisloLv']
+        end
+
+        def cadastral_unit_code
+          attributes['kodKatastralnihoUzemi']
+        end
+
+        def legal_basis
+          attributes['pravniDuvod']
+        end
+
+        def acquisition_date
+          attributes['datumNabiti']
+        end
+
+        def restrictions
+          attributes['omezeni'] || []
+        end
+
+        def encumbrances
+          attributes['vecnaBremena'] || []
+        end
+
+        private
+
+        def masked?
+          CUZK::REST.configuration.mask_personal_data
+        end
+
+        def summary_attributes
+          "id=#{id} owner=#{owner_name} share=#{ownership_share} lv=#{lv_number}"
+        end
+      end
+    end
+  end
+end