countriesdb-validator 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 026bd1abf019234cfa5a5e08a050b3ab17c3e99e319bf57069443c3db9dbc863
-  data.tar.gz: aa98cd6d11a466069cce9e09bbf4338b98e47e27209f4201965ce5a0ebe57950
+  metadata.gz: 20fcd315ef042db5a02d2f38ae2ea88bed36a5a06e56d0bb2e86adfb8392fc88
+  data.tar.gz: 02dd3af60deb0fc770a8b744604280ad5b0e2e385c95aefc017af2f7eaa3936b
 SHA512:
-  metadata.gz: 6b6aeebf408fa743eec4c54854169d179359bed45299de778ae5935a7d9d4b398a580ed3bd874ca5e96ce06f3f24dd748b2174095be3303bd68f2db43c95efe4
-  data.tar.gz: fb946815907c2308c9c55551aedc1b408db7621eba1b9acc4da6c141860d81dc89375de4789398a55a0036dbf6cca016dd4f594a6e07cface9a379c4b99eff30
+  metadata.gz: 28cbe56f977aea0d43557d2c690ba9391ce8ef9ec03739c617f4d32f2b1c26d9a257d99b8dc9984e8fd1689f3a8f35c2daf1b8f2c184e074add7a7cc6ab247f0
+  data.tar.gz: 2341e668e3fd206734b3ea017e4e59c727f78f6c204bf2f9dcb96db9aaaabb3e26301e363d5d3596ff95362f48746e4071b660a488b266c2329d26f0538add3d

data/README.md

@@ -199,6 +199,52 @@ post '/api/user' do
 end
 ```
 
+## Error Handling
+
+### Single-Value Methods
+
+Single-value methods (`validate_country`, `validate_subdivision`) return validation results with `valid: false` for invalid input. They only raise exceptions on network errors:
+
+```ruby
+begin
+  result = validator.validate_country('US')
+  unless result[:valid]
+    puts "Validation failed: #{result[:message]}"
+  end
+rescue StandardError => e
+  puts "Network error: #{e.message}"
+end
+```
+
+### Multi-Value Methods
+
+Multi-value methods (`validate_countries`, `validate_subdivisions`) return per-item results. Invalid codes are included in the results array with `valid: false`. They only raise exceptions on network errors or invalid input types:
+
+```ruby
+begin
+  results = validator.validate_countries(['US', 'BAD', 'CA'])
+  # Results: [
+  #   {code: 'US', valid: true},
+  #   {code: 'BAD', valid: false, message: 'Invalid country code.'},
+  #   {code: 'CA', valid: true}
+  # ]
+  
+  results.each do |result|
+    unless result[:valid]
+      puts "Code #{result[:code]} failed: #{result[:message]}"
+    end
+  end
+rescue StandardError => e
+  puts "Network error: #{e.message}"
+end
+```
+
+**Note:** 
+- Empty arrays return empty results arrays (not an error)
+- Basic type checks are performed client-side (e.g., ensuring arrays are arrays, country is a string)
+- Format validation (e.g., 2-character country codes) is handled by the backend and included in results with appropriate error messages
+- Invalid format codes or invalid country codes are returned in the results array with `valid: false` rather than raising exceptions
+
 ## Requirements
 
 - Ruby 2.7+

data/lib/countriesdb/validator.rb

@@ -38,14 +38,8 @@ module CountriesDB
     # @param codes [Array<String>] Array of ISO 3166-1 alpha-2 country codes
     # @return [Array<Hash>] Array of results with :code, :valid, and optional :message
     def validate_countries(codes, follow_upward: false)
-      return [] if codes.nil? || codes.empty?
-
-      # Validate format
-      codes.each do |code|
-        if code.nil? || code.length != 2
-          raise ArgumentError, 'Invalid country code format. All codes must be 2-character strings.'
-        end
-      end
+      raise ArgumentError, 'Codes must be an array' unless codes.is_a?(Array)
+      return [] if codes.empty?
 
       begin
         response = make_request('/api/validate/country', {
@@ -89,8 +83,11 @@ module CountriesDB
     # @param allow_parent_selection [Boolean] Whether to allow selecting parent subdivisions
     # @return [Array<Hash>] Array of results with :code, :valid, and optional :message
     def validate_subdivisions(codes, country, follow_related: false, allow_parent_selection: false)
-      raise ArgumentError, 'Invalid country code.' if country.nil? || country.length != 2
-      return [] if codes.nil? || codes.empty?
+      raise ArgumentError, 'Codes must be an array' unless codes.is_a?(Array)
+      return [] if codes.empty?
+
+      # Basic type check for country - format validation handled by backend
+      raise ArgumentError, 'Country must be a string' unless country.is_a?(String)
 
       begin
         response = make_request('/api/validate/subdivision', {

data/lib/countriesdb/version.rb

@@ -1,5 +1,5 @@
 module CountriesDB
-  VERSION = '1.0.2'
+  VERSION = '1.0.3'
 end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: countriesdb-validator
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - NAYEE LLC
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-23 00:00:00.000000000 Z
+date: 2026-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json