Class: CountriesDB::Validator

Inherits:
Object
  • Object
show all
Defined in:
lib/countriesdb/validator.rb

Overview

Validator class for CountriesDB backend API

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, backend_url: nil) ⇒ Validator

Returns a new instance of Validator.

Raises:

  • (ArgumentError) 


10
11
12
13
14
15
 
# File 'lib/countriesdb/validator.rb', line 10

def initialize(api_key:, backend_url: nil)
  raise ArgumentError, 'API key is required' if api_key.nil? || api_key.empty?

  @api_key = api_key
  @backend_url = backend_url || 'https://api.countriesdb.com'
end

Instance Attribute Details

#api_key ⇒ Object (readonly)

Returns the value of attribute api_key.



8
9
10
 
# File 'lib/countriesdb/validator.rb', line 8

def api_key
  @api_key
end

Instance Method Details

#validate_countries(codes, follow_upward: false) ⇒ Array<Hash>

Validate multiple country codes

Parameters:

  • codes (Array<String>) —

    Array of ISO 3166-1 alpha-2 country codes

Returns:

  • (Array<Hash>) —

    Array of results with :code, :valid, and optional :message



40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/countriesdb/validator.rb', line 40

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

  begin
    response = make_request('/api/validate/country', {
      code: codes.map(&:upcase),
      follow_upward: false # Disabled for multi-select
    })
    response[:results] || []
  rescue StandardError => e
    raise ValidationError, "Failed to validate countries: #{e.message}"
  end
end

#validate_country(code, follow_upward: false) ⇒ Hash

Validate a single country code

Parameters:

  • code (String) —

    ISO 3166-1 alpha-2 country code

  • follow_upward (Boolean) (defaults to: false) —

    Whether to check if country is referenced in a subdivision

Returns:

  • (Hash) —

    Result with :valid (Boolean) and optional :message (String)



22
23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/countriesdb/validator.rb', line 22

def validate_country(code, follow_upward: false)
  return invalid_result('Invalid country code.') if code.nil? || code.length != 2

  begin
    response = make_request('/api/validate/country', {
      code: code.upcase,
      follow_upward: follow_upward
    })
    response
  rescue StandardError => e
    invalid_result(e.message)
  end
end

#validate_subdivision(code, country, follow_related: false, allow_parent_selection: false) ⇒ Hash

Validate a single subdivision code

Parameters:

  • code (String, nil) —

    Subdivision code (e.g., ‘US-CA’) or nil/empty string

  • country (String) —

    ISO 3166-1 alpha-2 country code

  • follow_related (Boolean) (defaults to: false) —

    Whether to check if subdivision redirects to another country

  • allow_parent_selection (Boolean) (defaults to: false) —

    Whether to allow selecting parent subdivisions

Returns:

  • (Hash) —

    Result with :valid (Boolean) and optional :message (String)



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/countriesdb/validator.rb', line 68

def validate_subdivision(code, country, follow_related: false, allow_parent_selection: false)
  return invalid_result('Invalid country code.') if country.nil? || country.length != 2

  begin
    response = make_request('/api/validate/subdivision', {
      code: code || '',
      country: country.upcase,
      follow_related: follow_related,
      allow_parent_selection: allow_parent_selection
    })
    response
  rescue StandardError => e
    invalid_result(e.message)
  end
end

#validate_subdivisions(codes, country, follow_related: false, allow_parent_selection: false) ⇒ Array<Hash>

Validate multiple subdivision codes

Parameters:

  • codes (Array<String, nil>) —

    Array of subdivision codes or nil/empty strings

  • country (String) —

    ISO 3166-1 alpha-2 country code

  • follow_related (Boolean) (defaults to: false) —

    Whether to check if subdivision redirects to another country

  • allow_parent_selection (Boolean) (defaults to: false) —

    Whether to allow selecting parent subdivisions

Returns:

  • (Array<Hash>) —

    Array of results with :code, :valid, and optional :message

Raises:

  • (ArgumentError) 


91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/countriesdb/validator.rb', line 91

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?

  begin
    response = make_request('/api/validate/subdivision', {
      code: codes.map { |c| c || '' },
      country: country.upcase,
      follow_related: false, # Disabled for multi-select
      allow_parent_selection: allow_parent_selection
    })
    response[:results] || []
  rescue StandardError => e
    raise ValidationError, "Failed to validate subdivisions: #{e.message}"
  end
end