countriesdb-validator 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fe17836873cfdf5121f0ed749ae6ab13302c3f2341533bfef346a5254fff8e24
+  data.tar.gz: be1c0723cf2f27ba93c8565d7dba18c42dc33a75a67ed7b3426c7060544216e2
+SHA512:
+  metadata.gz: 53fa0e51b86cc0ef0d255fb8da6583ecf65b0e7c3f56bfe27d8a89b47663861193bdf9fb6cba4ec96ca47982a0f5811e60f5cefc4265244e2fe13bd2093c3838
+  data.tar.gz: 55bb861b16609100657fd11fa4f60903a341e0c057d2451f0edbaa537af412a3960fc327e901726bd44f20ce9d6a27a3bea1009d443e332086f37bf9f292d5e7

data/README.md

@@ -0,0 +1,221 @@
+# countriesdb-validator
+
+**Backend validation package for CountriesDB.** Provides server-side validation for country and subdivision codes using ISO 3166-1 and ISO 3166-2 standards.
+
+[![Gem Version](https://badge.fury.io/rb/countriesdb-validator.svg)](https://badge.fury.io/rb/countriesdb-validator)
+📖 **[Full Documentation](https://countriesdb.com/docs/backend-api)** | 🌐 **[Website](https://countriesdb.com)** | 📦 **[GitHub Repository](https://github.com/countriesdb/validator-ruby)**
+
+**Important**: This package only provides validation methods. Data fetching for frontend widgets must be done through frontend packages ([`@countriesdb/widget-core`](https://www.npmjs.com/package/@countriesdb/widget-core), [`@countriesdb/widget`](https://www.npmjs.com/package/@countriesdb/widget)).
+
+## Getting Started
+
+**⚠️ API Key Required:** This package requires a CountriesDB **private** API key to function. You must create an account at [countriesdb.com](https://countriesdb.com) to obtain your private API key. Test accounts are available with limited functionality.
+
+- 🔑 [Get your API key](https://countriesdb.com) - Create an account and get your private key
+- 📚 [View documentation](https://countriesdb.com/docs/backend-api) - Complete API reference and examples
+- 💬 [Support](https://countriesdb.com) - Get help and support
+
+## Features
+
+- ✅ **ISO 3166 Compliant** - Validates ISO 3166-1 (countries) and ISO 3166-2 (subdivisions) codes
+- ✅ **Multiple Validation Options** - Support for `follow_upward`, `follow_related`, and `allow_parent_selection`
+- ✅ **Batch Validation** - Validate multiple countries or subdivisions in a single request
+- ✅ **Rails Integration** - Built-in ActiveModel validators for seamless Rails integration
+- ✅ **Detailed Error Messages** - Returns specific error messages from the CountriesDB API
+
+## Installation
+
+```bash
+gem install countriesdb-validator
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'countriesdb-validator'
+```
+
+## Usage
+
+### Standalone Validator
+
+```ruby
+require 'countriesdb-validator'
+
+validator = CountriesDB::Validator.new(api_key: 'YOUR_API_KEY')
+
+# Validate a single country
+result = validator.validate_country('US')
+if result[:valid]
+  puts "Valid country"
+else
+  puts "Invalid: #{result[:message]}"
+end
+
+# Validate a single subdivision
+result = validator.validate_subdivision('US-CA', 'US')
+if result[:valid]
+  puts "Valid subdivision"
+end
+
+# Validate multiple countries
+results = validator.validate_countries(['US', 'CA', 'MX'])
+results.each do |result|
+  puts "#{result[:code]}: #{result[:valid] ? 'Valid' : 'Invalid'}"
+end
+
+# Validate multiple subdivisions
+results = validator.validate_subdivisions(
+  ['US-CA', 'US-NY', 'US-TX'],
+  'US'
+)
+```
+
+### Rails Validation
+
+#### Configuration
+
+Add to `config/application.rb` or `config/environments/*.rb`:
+
+```ruby
+config.countriesdb = {
+  api_key: 'YOUR_API_KEY'
+}
+```
+
+#### Using Validators
+
+```ruby
+class User < ApplicationRecord
+  validates :country, countriesdb: true
+  validates :subdivision, countriesdb: { subdivision: true, country: :country }
+end
+
+# With options
+class User < ApplicationRecord
+  validates :country, countriesdb: { follow_upward: true }
+  validates :subdivision, countriesdb: {
+    subdivision: true,
+    country: :country,
+    follow_related: true,
+    allow_parent_selection: true
+  }
+end
+```
+
+## API Reference
+
+### `CountriesDB::Validator`
+
+Main validator class.
+
+#### Constructor
+
+```ruby
+CountriesDB::Validator.new(api_key:)
+```
+
+**Parameters:**
+- `api_key` (required): Your CountriesDB API key
+
+#### Methods
+
+##### `validate_country(code, follow_upward: false)`
+
+Validate a single country code.
+
+**Parameters:**
+- `code` (String): ISO 3166-1 alpha-2 country code
+- `follow_upward` (Boolean): Check if country is referenced in a subdivision (default: `false`)
+
+**Returns:** Hash with `:valid` (Boolean) and optional `:message` (String)
+
+##### `validate_countries(codes, follow_upward: false)`
+
+Validate multiple country codes.
+
+**Parameters:**
+- `codes` (Array<String>): Array of ISO 3166-1 alpha-2 country codes
+- `follow_upward` (Boolean): Always false for multi-value (disabled)
+
+**Returns:** Array of results with `:code`, `:valid`, and optional `:message`
+
+##### `validate_subdivision(code, country, follow_related: false, allow_parent_selection: false)`
+
+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): Check if subdivision redirects to another country (default: `false`)
+- `allow_parent_selection` (Boolean): Allow selecting parent subdivisions (default: `false`)
+
+**Returns:** Hash with `:valid` (Boolean) and optional `:message` (String)
+
+##### `validate_subdivisions(codes, country, follow_related: false, allow_parent_selection: false)`
+
+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): Always false for multi-value (disabled)
+- `allow_parent_selection` (Boolean): Allow selecting parent subdivisions (default: `false`)
+
+**Returns:** Array of results with `:code`, `:valid`, and optional `:message`
+
+## Examples
+
+Runnable examples using this package are available in the [countriesdb/examples](https://github.com/countriesdb/examples) repository:
+
+- [`ruby/backend-faraday`](https://github.com/countriesdb/examples/tree/main/ruby/backend-faraday) – HTTP client examples using Faraday
+
+### Sinatra Example
+
+```ruby
+require 'sinatra'
+require 'countriesdb-validator'
+
+validator = CountriesDB::Validator.new(api_key: 'YOUR_API_KEY')
+
+post '/api/user' do
+  country = params[:country]
+  subdivision = params[:subdivision]
+
+  country_result = validator.validate_country(country)
+  unless country_result[:valid]
+    status 422
+    return { error: country_result[:message] }.to_json
+  end
+
+  subdivision_result = validator.validate_subdivision(subdivision, country)
+  unless subdivision_result[:valid]
+    status 422
+    return { error: subdivision_result[:message] }.to_json
+  end
+
+  # Validation passed
+  { message: 'Valid data' }.to_json
+end
+```
+
+## Requirements
+
+- Ruby 2.7+
+- Valid CountriesDB API key
+
+## License
+
+Proprietary
+Copyright (c) NAYEE LLC. All rights reserved.
+
+This software is the proprietary property of NAYEE LLC. For licensing inquiries, please contact [NAYEE LLC](https://nayee.net).
+
+
+
+
+
+
+
+
+

data/lib/countriesdb/rails/validators.rb

@@ -0,0 +1,58 @@
+# Rails validators for CountriesDB
+require 'active_model'
+
+module CountriesDB
+  module Rails
+    # ActiveModel validator for country codes
+    class CountriesdbValidator < ActiveModel::EachValidator
+      def validate_each(record, attribute, value)
+        api_key = Rails.application.config.countriesdb&.dig(:api_key) ||
+                  ENV['COUNTRIESDB_API_KEY']
+        backend_url = Rails.application.config.countriesdb&.dig(:backend_url) ||
+                      ENV['COUNTRIESDB_BACKEND_URL'] ||
+                      'https://api.countriesdb.com'
+
+        return if api_key.nil? || api_key.empty?
+
+        validator = CountriesDB::Validator.new(api_key: api_key, backend_url: backend_url)
+
+        # Determine validation type
+        if options[:subdivision]
+          country_attr = options[:country] || :country
+          country = record.send(country_attr)
+          result = validator.validate_subdivision(
+            value,
+            country,
+            follow_related: options[:follow_related] || false,
+            allow_parent_selection: options[:allow_parent_selection] || false
+          )
+        else
+          result = validator.validate_country(
+            value,
+            follow_upward: options[:follow_upward] || false
+          )
+        end
+
+        unless result[:valid]
+          record.errors.add(attribute, result[:message] || 'is invalid')
+        end
+      end
+    end
+  end
+end
+
+# Register the validator
+ActiveModel::Validations::HelperMethods.module_eval do
+  def validates_countriesdb(*attr_names)
+    validates_with CountriesDB::Rails::CountriesdbValidator, _merge_attributes(attr_names)
+  end
+end
+
+
+
+
+
+
+
+
+

data/lib/countriesdb/validator.rb

@@ -0,0 +1,163 @@
+require 'net/http'
+require 'json'
+require 'uri'
+
+module CountriesDB
+  # Validator class for CountriesDB backend API
+  class Validator
+    attr_reader :api_key
+
+    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
+
+    # Validate a single country code
+    #
+    # @param code [String] ISO 3166-1 alpha-2 country code
+    # @param follow_upward [Boolean] Whether to check if country is referenced in a subdivision
+    # @return [Hash] Result with :valid (Boolean) and optional :message (String)
+    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 multiple country codes
+    #
+    # @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
+
+      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 a single subdivision code
+    #
+    # @param code [String, nil] Subdivision code (e.g., 'US-CA') or nil/empty string
+    # @param country [String] ISO 3166-1 alpha-2 country code
+    # @param follow_related [Boolean] Whether to check if subdivision redirects to another country
+    # @param allow_parent_selection [Boolean] Whether to allow selecting parent subdivisions
+    # @return [Hash] Result with :valid (Boolean) and optional :message (String)
+    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 multiple subdivision codes
+    #
+    # @param codes [Array<String, nil>] Array of subdivision codes or nil/empty strings
+    # @param country [String] ISO 3166-1 alpha-2 country code
+    # @param follow_related [Boolean] Whether to check if subdivision redirects to another country
+    # @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?
+
+      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
+
+    private
+
+    def make_request(endpoint, data)
+      uri = URI.join(@backend_url, endpoint)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = 5
+      http.read_timeout = 10
+
+      request = Net::HTTP::Post.new(uri.path)
+      request['Content-Type'] = 'application/json'
+      request['Authorization'] = "Bearer #{@api_key}"
+      request.body = data.to_json
+
+      response = http.request(request)
+
+      unless response.code == '200'
+        error_data = JSON.parse(response.body) rescue {}
+        raise StandardError, error_data['message'] || "HTTP Error: #{response.code}"
+      end
+
+      JSON.parse(response.body)
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise TimeoutError, "Request timeout: #{e.message}"
+    rescue Net::HTTPError, SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH => e
+      raise ConnectionError, "Connection failed: #{e.message}"
+    rescue JSON::ParserError => e
+      raise StandardError, "Invalid JSON response: #{e.message}"
+    end
+
+    def invalid_result(message)
+      { valid: false, message: message }
+    end
+  end
+
+  # Exception for validation errors
+  class ValidationError < StandardError
+  end
+
+  # Exception for timeout errors
+  class TimeoutError < StandardError
+  end
+
+  # Exception for connection errors
+  class ConnectionError < StandardError
+  end
+end
+
+
+
+
+
+
+
+
+

data/lib/countriesdb/version.rb

@@ -0,0 +1,12 @@
+module CountriesDB
+  VERSION = '1.0.0'
+end
+
+
+
+
+
+
+
+
+

data/lib/countriesdb-validator.rb

@@ -0,0 +1,4 @@
+# Compatibility file for countriesdb-validator gem
+# Allows both require 'countriesdb' and require 'countriesdb-validator'
+require_relative 'countriesdb'
+

data/lib/countriesdb.rb

@@ -0,0 +1,22 @@
+# Main CountriesDB module
+require_relative 'countriesdb/version'
+require_relative 'countriesdb/validator'
+
+# Conditionally load Rails validators if ActiveModel is available
+if defined?(ActiveModel)
+  require_relative 'countriesdb/rails/validators'
+end
+
+module CountriesDB
+  # Main module for CountriesDB Ruby gem
+  # Provides backend validation for country and subdivision codes
+end
+
+
+
+
+
+
+
+
+

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: countriesdb-validator
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- NAYEE LLC
+- CountriesDB
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-12-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Server-side validation for country and subdivision codes
+email:
+- contact@nayee.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/countriesdb-validator.rb
+- lib/countriesdb.rb
+- lib/countriesdb/rails/validators.rb
+- lib/countriesdb/validator.rb
+- lib/countriesdb/version.rb
+homepage: https://countriesdb.com
+licenses:
+- Nonstandard
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Backend validation package for CountriesDB
+test_files: []