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

Raises:

  • (ArgumentError) 


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

def validate_countries(codes, follow_upward: false)
  raise ArgumentError, 'Codes must be an array' unless codes.is_a?(Array)
  return [] if codes.empty?

  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)



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/countriesdb/validator.rb', line 62

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) 


85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/countriesdb/validator.rb', line 85

def validate_subdivisions(codes, country, follow_related: false, allow_parent_selection: false)
  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', {
      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