ares_rest 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1157c4e6280ca0a075b900c9c6d3966d9ff6bc55c07edf3d1fcb862fac6581e0
+  data.tar.gz: a8f87d8e82b7e8cd6fcd5e244c68fa62a342eab0be2ead87977f35bebe82bb7c
+SHA512:
+  metadata.gz: a95bf05d02767b4036a2180237f1085e05dad83cac417657da6488f29ddafeeb7a548f40e477b195a5ef9d348a7b9a4f4fe6299b4340d01450405a0d73f47404
+  data.tar.gz: 9ccd38d547fb8b8597580dfb457a177b13f57971c4a78153ac97ca5ba9a99460c2e59aaf40f94f0f506ee68fc80d749ac99b3a5e95cefd0c829301cb1318d42e

data/.yardopts

@@ -0,0 +1,3 @@
+--no-private
+lib/**/*.rb
+- README.md CHANGELOG.md LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-10-08
+
+- Initial release
+- Add `AresRest.find` to look up a company by IČO
+- Add `AresRest::Subject` with name, DIČ, registered address and the raw response via `data`
+- Add `NotFoundError` and `InvalidIcoError`; network and parsing failures raise `AresRest::Error`

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"ares_rest" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["tomaslepicg@gmail.com"](mailto:"tomaslepicg@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 lepi1
+
+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,39 @@
+# AresRest
+
+Simple Ruby client for the Czech [ARES](https://ares.gov.cz/) registry. Finds a company by IČO.
+
+## Installation
+
+```ruby
+gem "ares_rest", github: "lepi1/ares_rest"
+```
+
+## Usage
+
+```ruby
+company = AresRest.find("12345678")
+company.name   # => "Example s.r.o."
+company.street # => "Hlavní 123/4"
+```
+
+Returns an `AresRest::Subject`. Other attributes: `ico`, `dic`, `city`, `postal_code`, `address`. There is also `to_h`.
+
+For fields not mapped yet, use the raw ARES response:
+
+```ruby
+company.data["datumVzniku"] # => "2020-01-01"
+```
+
+Raises `AresRest::NotFoundError` when the IČO doesn't exist, `AresRest::InvalidIcoError` for a malformed IČO and `AresRest::Error` for anything else (network errors, timeouts). All of them inherit from `AresRest::Error`.
+
+## Development
+
+Run `bin/setup` to install dependencies, then `bundle exec rake` to run tests and RuboCop. `bin/console` gives you an interactive prompt.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/lepi1/ares_rest. Contributors are expected to follow the [code of conduct](https://github.com/lepi1/ares_rest/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)

data/Rakefile

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

data/lib/ares_rest/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AresRest
+  # Gem version.
+  VERSION = "0.1.0"
+end

data/lib/ares_rest.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+require_relative "ares_rest/version"
+
+# Module for calling Ares API
+# https://ares.gov.cz/swagger-ui/#/
+#
+# @example
+#   subject = AresRest.find("12345678")
+#   subject.name   # => "Example s.r.o."
+#   subject.street # => "Hlavní 123/4"
+module AresRest
+  # Base class for all errors raised by this gem.
+  class Error < StandardError; end
+
+  # Raised when ARES has no subject with the given IČO.
+  class NotFoundError < Error; end
+
+  # Raised when the IČO is malformed or ARES rejects it.
+  class InvalidIcoError < Error; end
+
+  BASE_URL = "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest"
+  BY_ICO_ENDPOINT = "#{BASE_URL}/ekonomicke-subjekty/%s".freeze
+  OPEN_TIMEOUT = 5
+  READ_TIMEOUT = 10
+  NETWORK_ERRORS = [
+    SocketError, Timeout::Error, IOError, SystemCallError, OpenSSL::SSL::SSLError
+  ].freeze
+  private_constant :BASE_URL, :BY_ICO_ENDPOINT, :OPEN_TIMEOUT, :READ_TIMEOUT, :NETWORK_ERRORS
+
+  # Economic subject (company, sole trader, association, ...) returned by ARES.
+  # The full parsed response is available via {#data}.
+  class Subject
+    # @return [String, nil] IČO, 8 digits
+    attr_reader :ico
+
+    # @return [String, nil] business name (obchodní jméno)
+    attr_reader :name
+
+    # @return [String, nil] VAT number (DIČ), e.g. "CZ12345678"
+    attr_reader :dic
+
+    # @return [String, nil] street with house number, e.g. "Hlavní 123/4a"
+    attr_reader :street
+
+    # @return [String, nil] municipality (název obce), without district,
+    #   e.g. "Praha" even for an address in Praha 4
+    attr_reader :city
+
+    # @return [String, nil] postal code (PSČ) without spaces, e.g. "11000"
+    attr_reader :postal_code
+
+    # @return [String, nil] full one-line address as formatted by ARES
+    attr_reader :address
+
+    # Raw parsed ARES response, for fields without their own accessor.
+    #
+    # @example
+    #   subject.data["datumVzniku"] # => "2020-01-01"
+    # @return [Hash{String => Object}]
+    attr_reader :data
+
+    # @api private
+    # @param data [Hash{String => Object}] parsed ARES response
+    def initialize(data)
+      @data = data
+      @ico = data["ico"]
+      @name = data["obchodniJmeno"]
+      @dic = data["dic"]
+      assign_address(data["sidlo"]) if data["sidlo"]
+    end
+
+    # @return [Hash{Symbol => String, nil}] mapped attributes, without {#data}
+    def to_h
+      { ico: ico, name: name, dic: dic, street: street, city: city, postal_code: postal_code, address: address }
+    end
+
+    # Short representation without the raw {#data}.
+    #
+    # @example
+    #   subject.inspect # => '#<AresRest::Subject ico="12345678" name="Example s.r.o.">'
+    # @return [String]
+    def inspect
+      "#<#{self.class} ico=#{ico.inspect} name=#{name.inspect}>"
+    end
+
+    private
+
+    def assign_address(location)
+      street = location["nazevUlice"] || location["nazevCastiObce"] || location["nazevObce"]
+
+      @street = "#{street} #{build_street_number_from(location)}".strip
+      @city = location["nazevObce"]
+      @postal_code = location["psc"]&.to_s&.gsub(/\s+/, "")
+      @address = location["textovaAdresa"]
+    end
+
+    def build_street_number_from(location)
+      orientacni = "#{location["cisloOrientacni"]}#{location["cisloOrientacniPismeno"]}"
+      [location["cisloDomovni"], orientacni].map(&:to_s).reject(&:empty?).join("/")
+    end
+  end
+
+  # Looks up an economic subject by IČO.
+  #
+  # @param ico [String, Integer] 1-8 digits; whitespace is stripped and
+  #   shorter numbers are padded with leading zeros
+  # @return [Subject]
+  # @raise [InvalidIcoError] if the IČO is malformed
+  # @raise [NotFoundError] if no subject has this IČO
+  # @raise [Error] on network failure, timeout or an unexpected response
+  # @example
+  #   AresRest.find("12345678").name # => "Example s.r.o."
+  def self.find(ico)
+    response = get(URI(format(BY_ICO_ENDPOINT, normalize_ico(ico))))
+
+    case response.code
+    when "200" then Subject.new(JSON.parse(response.body))
+    when "404" then raise NotFoundError, "Cannot find subject with ICO #{ico}"
+    when "400" then raise InvalidIcoError, "ARES rejected ICO #{ico}"
+    else raise Error, "Unexpected ARES response: HTTP #{response.code}"
+    end
+  rescue JSON::ParserError => e
+    raise Error, "Invalid ARES response: #{e.message}"
+  end
+
+  def self.normalize_ico(ico)
+    normalized = ico.to_s.gsub(/\s+/, "")
+    raise InvalidIcoError, "ICO must be 1-8 digits, got #{ico.inspect}" unless normalized.match?(/\A\d{1,8}\z/)
+
+    normalized.rjust(8, "0")
+  end
+
+  def self.get(uri)
+    Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT) do |http|
+      http.request(Net::HTTP::Get.new(uri, "Accept" => "application/json"))
+    end
+  rescue *NETWORK_ERRORS => e
+    raise Error, "Communication error: #{e.message}"
+  end
+
+  private_class_method :normalize_ico, :get
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: ares_rest
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- lepi1
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Look up Czech companies by ICO (IČO) using the official ARES REST API.
+email:
+- public@tomaslepic.cz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ares_rest.rb
+- lib/ares_rest/version.rb
+homepage: https://github.com/lepi1/ares_rest
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/lepi1/ares_rest
+  source_code_uri: https://github.com/lepi1/ares_rest
+  changelog_uri: https://github.com/lepi1/ares_rest/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Ruby client for the Czech ARES business registry API
+test_files: []