cuzk-rest 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f41325469105b4cb0016acf55195d3b3de369bf82a0e5584eb645ef0476330ee
+  data.tar.gz: d9acd5e9d4e8d1a53ca779165e8b1941fadd1d5553eb50ab53327af834ca6044
+SHA512:
+  metadata.gz: 015aa186bf405bd4f6b7ec43fe777cfb15fef66ec3ad3de9280717d63e8162e408284fa4e3b659bfb5dc1749c60f014ee16033620eef5132c23bb1fd9143268f
+  data.tar.gz: 4e87cc53f54d0320b565354aabfcd40cd3b2158fe027dfb52fd7fbc3738184e3feb5faf874a222ae6f62706f3d73e5a0e71c5ade9ce6fe31b0e230a83bdd5187

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,65 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+
+RSpec/DescribeClass:
+  Exclude:
+    - "spec/cuzk/rest/errors_spec.rb"
+    - "spec/integration/**/*"
+
+Layout/LineLength:
+  Max: 120
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/MultipleExpectations:
+  Max: 8
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+Naming/FileName:
+  Exclude:
+    - 'lib/cuzk-rest.rb'
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - x
+    - y
+    - id
+    - e
+
+Naming/PredicateMethod:
+  AllowedMethods:
+    - validate!
+
+Metrics/CyclomaticComplexity:
+  Max: 12
+
+Metrics/AbcSize:
+  Max: 50

data/.ruby-version

@@ -0,0 +1 @@
+3.4.2

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-02
+
+### Added
+
+- Initial release of the cuzk-rest gem
+- Core client with Faraday HTTP layer, rate limiting, and retry logic
+- Resource classes: Parcel, Building, Unit, Ownership
+- Supporting classes: Registry, Territory, Procedure, Search
+- Configuration with API key authentication
+- Full error hierarchy for API, network, data, and privacy errors
+- GDPR-aware privacy mode with personal data masking
+- Comprehensive RSpec test suite with WebMock stubs
+- CI/CD via GitHub Actions for Ruby 3.1-3.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Segfault Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,321 @@
+# cuzk-rest
+
+Ruby client for the [ČÚZK REST API](https://api-kn.cuzk.gov.cz/) (Czech Real Estate Registry / Katastr nemovitostí).
+
+Provides idiomatic Ruby access to cadastral data including parcels, buildings, units, procedures, territorial registries, and application services.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'cuzk-rest'
+```
+
+Or install directly:
+
+```sh
+gem install cuzk-rest
+```
+
+## Requirements
+
+- Ruby >= 3.1
+- ČÚZK REST API key ([request one here](https://www.cuzk.cz/))
+
+## Quick Start
+
+```ruby
+require 'cuzk-rest'
+
+# Configure globally
+CUZK::REST.configure do |config|
+  config.api_key = 'your-api-key'
+end
+
+# Or via environment variable CUZK_REST_API_KEY
+client = CUZK::REST::Client.new
+```
+
+## Usage
+
+### Client
+
+The `Client` class is the main entry point. It sets up the connection and provides convenience methods for all resources.
+
+```ruby
+client = CUZK::REST::Client.new(api_key: 'your-api-key')
+
+# Or with additional options
+client = CUZK::REST::Client.new(
+  api_key: 'your-api-key',
+  timeout: 60,
+  retries: 5
+)
+```
+
+### Parcels (Parcely)
+
+```ruby
+# Find a parcel by ID
+parcel = client.find_parcel(728_497)
+parcel.number          # => 1
+parcel.full_number     # => "1" or "123/4" with sub-number
+parcel.area            # => 56942
+parcel.land_type       # => "zastavěná plocha a nádvoří"
+parcel.cadastral_unit_name  # => "Hradčany"
+parcel.lv_number       # => 60
+
+# Search parcels
+parcels = client.search_parcels(cadastral_unit: '727091')
+parcels = client.search_parcels(number: '123', lv_number: '60')
+
+# Find by cadastral unit
+parcels = client.find_parcels_by_cadastral_unit('727091')
+
+# Find neighboring parcels
+neighbors = client.find_neighboring_parcels(728_497)
+```
+
+### Buildings (Stavby)
+
+```ruby
+# Find a building by ID
+building = client.find_building(1_950_001)
+building.descriptive_number  # => 1
+building.municipality        # => "Praha"
+building.street              # => "Hradčanské náměstí"
+building.full_address        # => "Hradčanské náměstí, 1, Hradčany, Praha, 11900"
+
+# Search buildings
+buildings = client.search_buildings(house_number: '100')
+
+# Find by address point code
+building = client.find_building_by_address_point(12_345)
+```
+
+### Units (Jednotky)
+
+```ruby
+# Find a unit by ID
+unit = client.find_unit(3001)
+unit.number               # => "100/1"
+unit.unit_type_description  # => "byt"
+unit.area                  # => 65
+unit.ownership_share       # => "65/1000"
+unit.share_percentage      # => 6.5
+
+# Search units
+units = client.search_units(house_number: '100', unit_number: '1')
+
+# Find units in a building
+units = client.find_units_by_building('100')
+```
+
+### Procedures (Rizeni)
+
+```ruby
+# Find a procedure by ID
+procedure = client.find_procedure(5001)
+procedure.procedure_number  # => "V-12345/2024-611"
+procedure.active?           # => true
+
+# Search procedures
+procedures = client.search_procedures(cadastral_unit: '727091')
+
+# Active procedures only
+procedures = client.active_procedures(cadastral_unit: '727091')
+
+# Procedures received on a specific date
+procedures = client.procedures_received_on('2024-06-15')
+```
+
+### Building Rights (Prava stavby)
+
+```ruby
+# Find a building right by ID
+right = client.find_building_right(6001)
+
+# Find by parcel or building
+rights = client.find_building_rights_by_parcel(1001)
+rights = client.find_building_rights_by_building(2001)
+```
+
+### Registries (Ciselniky ISKN)
+
+```ruby
+registries = client.registries
+
+# Fetch registry lists
+land_types   = registries.land_types
+building_types = registries.building_types
+unit_types   = registries.unit_types
+protection_types = registries.protection_types
+land_use_types   = registries.land_use_types
+
+# Translate codes
+name = registries.translate_code(2, registry_type: 'DruhyPozemku')
+# => "orná půda"
+
+# Find code by description
+code = registries.find_code('vinice', registry_type: 'DruhyPozemku')
+# => 3
+```
+
+### Territories (Ciselniky uzemních jednotek)
+
+```ruby
+# Regions (Kraje)
+regions = client.regions  # => all 14 Czech regions
+
+# Districts (Okresy)
+districts = client.districts(region: '116')
+
+# Municipalities (Obce)
+municipalities = client.municipalities(district: '3702')
+
+# Cadastral units (Katastralni uzemi)
+units = client.cadastral_units(municipality: '582786')
+```
+
+### Health Check
+
+```ruby
+# Test connectivity (no auth required)
+result = client.health
+result.status  # => "Healthy"
+
+# Simple boolean check
+client.test_connection  # => true / false
+```
+
+## Configuration
+
+```ruby
+CUZK::REST.configure do |config|
+  # Required
+  config.api_key = 'your-api-key'
+
+  # Optional (shown with defaults)
+  config.base_url = 'https://api-kn.cuzk.gov.cz'
+  config.api_version = 'v1'
+  config.timeout = 30            # request timeout in seconds
+  config.open_timeout = 10       # connection open timeout
+  config.retries = 3             # retry count for 429/5xx
+  config.retry_interval = 0.5    # seconds between retries
+  config.requests_per_minute = 60
+  config.burst_limit = 10
+
+  # Privacy
+  config.mask_personal_data = true   # mask owner names (GDPR)
+  config.privacy_mode = :strict
+
+  # Logging
+  config.logger = Logger.new($stdout)
+  config.log_requests = true
+  config.log_responses = true
+end
+```
+
+The API key can also be set via the `CUZK_REST_API_KEY` environment variable.
+
+## Error Handling
+
+All API errors inherit from `CUZK::REST::Error`:
+
+```ruby
+begin
+  client.find_parcel(9999)
+rescue CUZK::REST::NotFoundError => e
+  puts "Not found: #{e.message}"
+rescue CUZK::REST::AuthenticationError
+  puts "Invalid API key"
+rescue CUZK::REST::RateLimitedError
+  puts "Rate limit exceeded, try again later"
+rescue CUZK::REST::TimeoutError
+  puts "Request timed out"
+rescue CUZK::REST::APIError => e
+  puts "API error #{e.status}: #{e.message}"
+end
+```
+
+Error hierarchy:
+
+```
+Error
+├── ConfigurationError
+├── APIError
+│   ├── AuthenticationError (401)
+│   ├── AuthorizationError (403)
+│   ├── NotFoundError (404)
+│   ├── ValidationError (422)
+│   ├── RateLimitedError (429)
+│   └── ServerError (5xx)
+├── NetworkError
+│   ├── TimeoutError
+│   └── ConnectionError
+├── DataError
+│   ├── ParsingError
+│   └── InvalidResponseError
+└── PrivacyError
+    └── GDPRViolationError
+```
+
+## Response Metadata
+
+The ČÚZK API wraps responses in an envelope containing metadata. After any request, you can access it via the connection:
+
+```ruby
+client.find_parcel(728_497)
+metadata = client.connection.last_response_metadata
+metadata['zpravy']          # => [] (messages/warnings)
+metadata['aktualnostDatK']  # => "2024-12-01T00:00:00" (data currency)
+metadata['provedenoVolani'] # => 1.0 (call count)
+```
+
+## API Endpoints
+
+This gem maps to the following ČÚZK REST API endpoints:
+
+| Resource | API Path | Methods |
+|---|---|---|
+| Parcel | `Parcely` | find, search (Vyhledani), SousedniParcely |
+| Building | `Stavby` | find, search (Vyhledani), AdresniMisto |
+| Unit | `Jednotky` | find, search (Vyhledani) |
+| Procedure | `Rizeni` | find, search (Vyhledani), PrijateDne |
+| Building Right | `PravaStavby` | find, Parcela, Stavba |
+| Registry | `CiselnikyISKN` | DruhyPozemku, TypyStavby, TypyJednotky, ... |
+| Territory | `CiselnikyUzemnichJednotek` | Kraje, Okresy, Obce, CastiObci, KatastralniUzemi |
+| App Service | `AplikacniSluzby` | Health, StavUctu, AktualnostDat |
+
+## Development
+
+```sh
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run only unit tests (no integration)
+bundle exec rspec --exclude-pattern 'spec/integration/**/*'
+
+# Run integration tests (VCR cassettes)
+bundle exec rspec spec/integration/ --tag ~live
+
+# Run live health check (requires API key)
+CUZK_REST_API_KEY=your-key bundle exec rspec spec/integration/ --tag live
+
+# Lint
+bundle exec rubocop
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Links
+
+- [ČÚZK REST API](https://api-kn.cuzk.gov.cz/)
+- [API Swagger Docs](https://api-kn.cuzk.gov.cz/swagger/v1.0/swagger.json)
+- [ČÚZK (Czech Office for Surveying, Mapping and Cadastre)](https://www.cuzk.cz/)

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/cuzk/rest/client.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module CUZK
+  module REST
+    class Client
+      attr_reader :config, :connection
+
+      class << self
+        def default_connection
+          @default_connection || raise(ConfigurationError, 'No client configured. Use CUZK::REST::Client.new first.')
+        end
+
+        attr_writer :default_connection
+      end
+
+      def initialize(api_key: nil, **options)
+        @config = build_config(api_key, options)
+        @connection = Connection.new(@config)
+        assign_connection_to_resources
+
+        yield self if block_given?
+      end
+
+      # --- Parcel Operations ---
+
+      def find_parcel(parcel_id)
+        Resources::Parcel.find(parcel_id)
+      end
+
+      def search_parcels(params = {})
+        Resources::Parcel.search(params)
+      end
+
+      def find_parcels_by_cadastral_unit(cadastral_unit_code, **params)
+        Resources::Parcel.find_by_cadastral_unit(cadastral_unit_code, params)
+      end
+
+      def find_neighboring_parcels(parcel_id)
+        Resources::Parcel.find_neighbors(parcel_id)
+      end
+
+      # --- Building Operations ---
+
+      def find_building(building_id)
+        Resources::Building.find(building_id)
+      end
+
+      def search_buildings(params = {})
+        Resources::Building.search(params)
+      end
+
+      def find_building_by_address_point(address_code)
+        Resources::Building.find_by_address_point(address_code)
+      end
+
+      # --- Unit Operations ---
+
+      def find_unit(unit_id)
+        Resources::Unit.find(unit_id)
+      end
+
+      def search_units(params = {})
+        Resources::Unit.search(params)
+      end
+
+      def find_units_by_building(building_id)
+        Resources::Unit.find_by_building(building_id)
+      end
+
+      # --- Procedure Operations ---
+
+      def find_procedure(procedure_id)
+        Resources::Procedure.find(procedure_id)
+      end
+
+      def search_procedures(params = {})
+        Resources::Procedure.search(params)
+      end
+
+      def active_procedures(**params)
+        Resources::Procedure.active(params)
+      end
+
+      def procedures_received_on(date, **params)
+        Resources::Procedure.received_on(date, params)
+      end
+
+      # --- Building Right Operations ---
+
+      def find_building_right(id)
+        Resources::BuildingRight.find(id)
+      end
+
+      def find_building_rights_by_parcel(parcel_id)
+        Resources::BuildingRight.find_by_parcel(parcel_id)
+      end
+
+      def find_building_rights_by_building(building_id)
+        Resources::BuildingRight.find_by_building(building_id)
+      end
+
+      # --- Registry Operations ---
+
+      def registries
+        @registries ||= RegistryAccessor.new
+      end
+
+      # --- Territory Operations ---
+
+      def cadastral_units(**params)
+        Resources::Territory.cadastral_units(params)
+      end
+
+      def municipalities(**params)
+        Resources::Territory.municipalities(params)
+      end
+
+      def districts(**params)
+        Resources::Territory.districts(params)
+      end
+
+      def regions
+        Resources::Territory.regions
+      end
+
+      # --- App Service Operations ---
+
+      def health
+        Resources::AppService.health
+      end
+
+      # --- Connection Info ---
+
+      def test_connection
+        health
+        true
+      rescue Error
+        false
+      end
+
+      def connected?
+        !@connection.nil?
+      end
+
+      private
+
+      def build_config(api_key, options)
+        config = CUZK::REST.configuration.dup
+        config.api_key = api_key if api_key
+        options.each { |key, value| config.public_send(:"#{key}=", value) }
+        config
+      end
+
+      def assign_connection_to_resources
+        self.class.default_connection = @connection
+        resource_classes.each { |klass| klass.connection = @connection }
+      end
+
+      def resource_classes
+        [
+          Resources::Parcel,
+          Resources::Building,
+          Resources::Unit,
+          Resources::Ownership,
+          Resources::Registry,
+          Resources::Territory,
+          Resources::Procedure,
+          Resources::AppService,
+          Resources::BuildingRight
+        ]
+      end
+
+      # Convenience wrapper for registry access
+      class RegistryAccessor
+        def land_types
+          Resources::Registry.land_types
+        end
+
+        def building_types
+          Resources::Registry.building_types
+        end
+
+        def building_purposes
+          Resources::Registry.building_purposes
+        end
+
+        def unit_types
+          Resources::Registry.unit_types
+        end
+
+        def protection_types
+          Resources::Registry.protection_types
+        end
+
+        def land_use_types
+          Resources::Registry.land_use_types
+        end
+
+        def translate_code(code, registry_type:)
+          Resources::Registry.translate_code(code, registry_type: registry_type)
+        end
+
+        def find_code(description, registry_type:)
+          Resources::Registry.find_code(description, registry_type: registry_type)
+        end
+      end
+    end
+  end
+end