belpost 0.4.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d81d235b373255e2bff25ee56958cd6658a44e9546560ae96486986d278c1f0b
-  data.tar.gz: a155cca07102f767c12b05bf2c574fdb827f46cae00357e0b213c4daf0d35c84
+  metadata.gz: 5555f3f61fcb03030a1e5fd226abac810104277326db2ee42b505656ff0f3ce8
+  data.tar.gz: 585c4832344b4cfa9a654e4605926bacd605bf854e77e21391910de03d3d22db
 SHA512:
-  metadata.gz: cf7a95cd9ae059a9f0d4e10c3ac7e24cf7f94447817d9d104a58a2d2eb9382f4c13ea1fe5bb512589a9e92141ea92100632864a0637ac47150eed848af1d11d7
-  data.tar.gz: 4fa75a2f2af404733bcf1eff337ac0c102629d8c8ae67085e44858174e9f17975ffb70cced4e5444834801419391e484c340e5d9c87813ec1ce105f9616e2687
+  metadata.gz: eaf547611c62aa03df55771a57d4405ea1352b04cf9fe3fddd04f1120b3df24a100a38e4f449e7dcadffa1a7b1bd58101212425d263d7e168b448712af597d5c
+  data.tar.gz: 4eb26318bd0e28467e50a31caa184880fab8276e331efcd7240723124ebf3795615d47eca35516f7f0d5048dbf3bb44663bb25182815d807fd4aef9d59313899

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.7.0] - 2025-04-01
+### Added
+- Added postal code search functionality via `search_postcode` method
+- Support for searching postal codes by city, street, and building number
+- Added comprehensive tests for the new postal code search endpoint
+
+## [0.6.0] - 2025-04-01
+### Added
+- Added search addresses search functionality via `find_address_by_string` method
+
+## [0.5.1] - 2025-04-01
+### Fixed
+- Improved error handling for invalid timeout environment variable
+- Added fallback for BELPOST_API_URL environment variable to make tests more robust
+- Fixed Configuration class by implementing `validate!` and `to_h` methods
+
+## [0.5.0] - 2025-04-01
+### Added
+- Added address search functionality via `find_address_by_string` method
+- Support for query parameters in GET requests
+
 ## [0.4.0] - 2025-04-01
 ### Added
 - Added configuration via environment variables

data/README.md

@@ -295,6 +295,19 @@ hs_codes = client.fetch_hs_codes
 puts hs_codes
 ```
 
+### Searching for postal codes
+
+```ruby
+client = Belpost::Client.new
+postcodes = client.search_postcode(
+  city: "Витебск",
+  street: "Ильинского",
+  building: "51/1",  # optional
+  limit: 50          # optional, default: 50, range: 1-200
+)
+puts postcodes
+```
+
 ## Error handling
 
 The client may throw the following exceptions:

data/lib/belpost/api_service.rb

@@ -23,10 +23,12 @@ module Belpost
     # Performs a GET request to the specified path.
     #
     # @param path [String] The API endpoint path.
+    # @param params [Hash] The query parameters (default: {}).
     # @return [Models::ApiResponse] The parsed JSON response from the API.
-    def get(path)
+    def get(path, params = {})
       Retry.with_retry do
         uri = URI("#{@base_url}#{path}")
+        uri.query = URI.encode_www_form(params) unless params.empty?
         request = Net::HTTP::Get.new(uri)
         add_headers(request)
 

data/lib/belpost/client.rb

@@ -3,6 +3,7 @@
 require_relative "api_service"
 require_relative "models/parcel"
 require_relative "models/api_response"
+require_relative "validations/address_schema"
 
 module Belpost
   # Main client class for interacting with the BelPost API.
@@ -67,5 +68,75 @@ module Belpost
       response = @api_service.get("/api/v1/business/postal-deliveries/countries")
       response.to_h
     end
+
+    # Allows you to find an address by a string.
+    #
+    # Accepts a string with an address in any form and returns found addresses (up to 50 records).
+    # Building numbers should be specified without spaces: "building number""letter""building".
+    # The letter should be uppercase, and "building" (or "корп", "кор", "к") should be replaced with "/".
+    # Example: "город Минск улица Автодоровская 3Е корпус 4" should be transformed to "город Минск улица Автодоровская 3Е/4".
+    #
+    # @param address [String] The address string to search for.
+    # @return [Array<Hash>] An array of found addresses with postcode, region, city, street and other information.
+    # @raise [Belpost::ApiError] If the API returns an error response.
+    # @raise [Belpost::InvalidRequestError] If the address parameter is missing or has an incorrect format.
+    def find_address_by_string(address)
+      raise ValidationError, "Address must be filled" if address.nil?
+      raise ValidationError, "Address must be a string" unless address.is_a?(String)
+      raise ValidationError, "Address must be filled" if address.empty?
+
+      formatted_address = format_address(address)
+      response = @api_service.get("/api/v1/business/geo-directory/search-address", { search: formatted_address })
+      response.to_h
+    end
+
+    # Searches for postal codes by city, street, and building number.
+    #
+    # @param city [String] The city name (required)
+    # @param street [String] The street name (required)
+    # @param building [String] The building number (optional)
+    # @param limit [Integer] Maximum number of results (optional, default: 50, range: 1-200)
+    # @return [Array<Hash>] An array of found addresses with postcode, region, city, street and other information
+    # @raise [Belpost::ValidationError] If required parameters are missing or invalid
+    # @raise [Belpost::ApiError] If the API returns an error response
+    def search_postcode(city:, street:, building: nil, limit: 50)
+      raise ValidationError, "City must be filled" if city.nil?
+      raise ValidationError, "City must be a string" unless city.is_a?(String)
+      raise ValidationError, "City must be filled" if city.empty?
+      raise ValidationError, "Street must be filled" if street.nil?
+      raise ValidationError, "Street must be a string" unless street.is_a?(String)
+      raise ValidationError, "Street must be filled" if street.empty?
+      raise ValidationError, "Building must be a string" if building && !building.is_a?(String)
+      raise ValidationError, "Limit must be between 1 and 200" if limit < 1 || limit > 200
+
+      params = { city: city, street: street }
+      params[:building] = format_building_number(building) if building
+      params[:limit] = limit
+
+      response = @api_service.get("/api/v1/business/geo-directory/postcode", params)
+      response.to_h
+    end
+
+    private
+
+    def format_address(address)
+      address.gsub(/\s+/, " ")
+             .gsub(/\s*корпус\s*(\d+)\s*/i, '/\1')
+             .gsub(/\s*корп\s*(\d+)\s*/i, '/\1')
+             .gsub(/\s*кор\s*(\d+)\s*/i, '/\1')
+             .gsub(/\s*к\s*(\d+)\s*/i, '/\1')
+             .strip
+    end
+
+    def format_building_number(building)
+      return building unless building
+
+      building.gsub(/\s+/, " ")
+             .gsub(/\s*корпус\s*(\d+)\s*/i, '/\1')
+             .gsub(/\s*корп\s*(\d+)\s*/i, '/\1')
+             .gsub(/\s*кор\s*(\d+)\s*/i, '/\1')
+             .gsub(/\s*к\s*(\d+)\s*/i, '/\1')
+             .strip
+    end
   end
 end

data/lib/belpost/configuration.rb

@@ -7,9 +7,32 @@ module Belpost
     attr_accessor :base_url, :jwt_token, :timeout
 
     def initialize
-      @base_url = ENV.fetch("BELPOST_API_URL")
+      @base_url = ENV.fetch("BELPOST_API_URL", "https://api.belpost.by")
       @jwt_token = ENV.fetch("BELPOST_JWT_TOKEN", nil)
-      @timeout = ENV.fetch("BELPOST_TIMEOUT", 10).to_i
+      
+      # Convert timeout to integer with a fallback to default
+      begin
+        @timeout = Integer(ENV.fetch("BELPOST_TIMEOUT", 10))
+      rescue ArgumentError
+        @timeout = 10
+      end
+    end
+    
+    # Validates that all required configuration is present
+    # @raise [Belpost::ConfigurationError] If required configuration is missing
+    def validate!
+      raise ConfigurationError, "Base URL is required" if base_url.nil?
+      raise ConfigurationError, "JWT token is required" if jwt_token.nil?
+    end
+    
+    # Returns a hash representation of the configuration
+    # @return [Hash] The configuration as a hash
+    def to_h
+      {
+        base_url: base_url,
+        jwt_token: jwt_token,
+        timeout: timeout
+      }
     end
   end
 end

data/lib/belpost/validations/address_schema.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "dry-validation"
+
+module Belpost
+  module Validation
+    # Schema for validating and formatting address strings
+    class AddressSchema < Dry::Validation::Contract
+      params do
+        required(:address).filled(:string)
+      end
+
+      rule(:address) do
+        # Remove extra spaces
+        address = value.gsub(/\s+/, " ").strip
+        
+        # Replace building indicators with "/"
+        address = address.gsub(/\s+(корпус|корп|кор|к)\s+/, "/")
+        
+        # Ensure building number format (no spaces between number, letter, and building)
+        address = address.gsub(/(\d+)\s*([А-Я])\s*(\d+)/, '\1\2/\3')
+        
+        # Ensure letter is uppercase
+        address = address.gsub(/(\d+)([а-я])(\/\d+)/) { |m| "#{$1}#{$2.upcase}#{$3}" }
+        
+        key.failure(address)
+      end
+    end
+  end
+end 

data/lib/belpost/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Belpost
-  VERSION = "0.4.0"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belpost
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.7.0
 platform: ruby
 authors:
 - KuberLite
@@ -64,6 +64,7 @@ files:
 - lib/belpost/models/parcel.rb
 - lib/belpost/models/parcel_builder.rb
 - lib/belpost/retry.rb
+- lib/belpost/validations/address_schema.rb
 - lib/belpost/validations/parcel_schema.rb
 - lib/belpost/version.rb
 homepage: https://github.com/KuberLite/belpost