electionbuddy-ruby 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 609fbcd8ec13547ffc65048afb495236d9eecbe0a787bea74bee39315b3e92c1
-  data.tar.gz: 35682f5a36ea65fe229f9239cf14335b132e6ef94e7befc79d9e601338262e81
+  metadata.gz: 64c0f48e8da4cd5811d86506d945b853e4e284afd8a8041878d680bf46117d4d
+  data.tar.gz: b635df1e9e3f7f013c769818e2722f6224de5cea279bd5ad36364a80c6d9d15b
 SHA512:
-  metadata.gz: 7cbf3bc35b59210fcf1a8a0e906dafa5112ea801568edc5aee762019edc3dcdc49936087e7c58613657b3d732af42400ea735da644f717e38d89a2e1eb8b074b
-  data.tar.gz: 7fadf9a933f95c94b949dbec9533bf6c775cc25c16252e30f80d3895ab7c49408e29d01518e034d9d71148e6e258634ce01df6f7d4710625d21cfee4ff9ba431
+  metadata.gz: b0dc2ca445cb784a1d72b27c6bcd4a5f0221ea50ca87e577dd301e0603189a11623eb85f9d794005350486efd82ce62bdb40d1492afe5ef536cde58a39fdb060
+  data.tar.gz: 4438b38fefa9ebaf8d22d7b57bc71272042bf89eda5dfe459fe29d647fd1c7d0d6141e31c5befe25e7267c5010cf5fad67b7f8ab729ef067b155b68ceed07fea

data/.rubocop.yml

@@ -15,4 +15,10 @@ Naming/FileName:
     - 'lib/electionbuddy-ruby.rb'
 
 Metrics/MethodLength:
-  Max: 15
+  Max: 30
+
+Metrics/ClassLength:
+  Max: 200
+
+Layout/LineLength:
+  Max: 150

data/.yardopts

@@ -0,0 +1,10 @@
+--markup markdown
+--markup-provider redcarpet
+--readme README.md
+--title 'ElectionBuddy Ruby'
+--protected
+--private
+lib/**/*.rb
+-
+LICENSE.txt
+CHANGELOG.md

data/CHANGELOG.md

@@ -7,9 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.1.0] - 2024-10-29
+## [0.4.0] - 2024-11-20
 
-- Initial release
+### Added
+
+- Ability to import voters to a vote
+- Automated gem release using GitHub Actions
+
+## [0.3.0] - 2024-11-18
+
+### Added
+
+- Added Global configuration for setting the API key using `ElectionBuddy.configure` method
+- Ability to retrieve voter list's validation results
+- Automated gem documentation using YARD and GitHub Pages
+
+### Changed
+
+- Update README.md with get validtion results usage instructions
+- Update .rubocop.yml with new rules
+- Enhance code documentation with detailed YARD comments
+
+### Fixed
+
+- Fix changelog version ordering
 
 ## [0.2.0] - 2024-11-07
 
@@ -29,7 +50,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Fix console startup issue caused by incorrect code reference
 
-[unreleased]: https://github.com/electionbuddy/electionbuddy-ruby/compare/v0.2.0...HEAD
+## [0.1.0] - 2024-10-29
+
+- Initial release
+
+[unreleased]: https://github.com/electionbuddy/electionbuddy-ruby/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/electionbuddy/electionbuddy-ruby/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/electionbuddy/electionbuddy-ruby/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/electionbuddy/electionbuddy-ruby/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/electionbuddy/electionbuddy-ruby/releases/tag/v0.1.0
 

data/README.md

@@ -1,7 +1,7 @@
 # ElectionBuddy Ruby
 
-A Ruby client for interacting with the ElectionBuddy API.
-You can find the API documentation [here](https://api.electionbuddy.com).
+A Ruby client for interacting with the [ElectionBuddy API](https://api.electionbuddy.com).
+Explore the complete documentation at [https://electionbuddy.github.io/electionbuddy-ruby](https://electionbuddy.github.io/electionbuddy-ruby).
 
 ## Installation
 
@@ -21,12 +21,55 @@ gem 'electionbuddy-ruby'
 
 ## Usage
 
-Ensure you have an API key from Electionbuddy, and initialize the client as follows:
+Ensure you have an API key from Electionbuddy. You can configure the API key globally or initialize the client directly with the API key.
+
+### Global Configuration
+
+#### Example in a Rails application
+
+Create an initializer file in `config/initializers/electionbuddy.rb` and add the following code:
+
+```ruby
+ElectionBuddy.configure do |config|
+  config.api_key = Rails.application.credentials.electionbuddy[:api_key]
+end
+```
+
+#### Client Initialization
+
+You can now initialize the client without passing the API key if it has been configured globally:
 
 ```ruby
-client = ElectionBuddy::Client.new('your-api-key')
+client = ElectionBuddy::Client.new
 ```
 
+Alternatively, you can still pass the API key directly during initialization. If the API key is passed during initialization, it will take precedence over the global configuration.
+
+```ruby
+client = ElectionBuddy::Client.new(api_key: 'your-api-key')
+```
+
+### Voter List Importation
+
+To import a voter list for an election, use the `voter_list.import(vote_id, voters, append_mode: false)` method:
+
+```ruby
+voters = [
+  { email: 'voter1@example.com', label: 'Voter One' },
+  { email: 'voter2@example.com', label: 'Voter Two' }
+]
+
+import = client.voter_list.import(1, voters, append_mode: false)
+
+if import.done?
+  puts "Import completed successfully! Identifier: #{import.identifier}"
+else
+  puts "Import failed: #{import.error}"
+end
+```
+
+The `append_mode` parameter determines whether the voters should be appended to the existing list (`true`) or replace the existing list (`false`). The default value is `false`.
+
 ### Voter List Validation
 
 To validate a voter list, use the `voter_list.validate(vote_id)` method:
@@ -36,14 +79,79 @@ validation = client.voter_list.validate(1)
 
 if validation.done?
   puts "Validation completed successfully! Identifier: #{validation.identifier}"
-  # "Validation completed successfully! Identifier: ae0a1724-9791-4bb2-8331-6d4e55a9b7c8"
 else
   puts "Validation failed: #{validation.error}"
-  # "Validation failed: Vote: not found"
 end
 ```
 
-### Possible Errors
+### Get the Validation Result
+
+Once you have a validation identifier, you can check the validation results. 
+
+```ruby
+begin
+  validation_result = client.voter_list.validation_result('ae0a1724-9791-4bb2-8331-6d4e55a9b7c8')
+  if validation_result.valid?
+    puts "The voter list is valid!"
+  else
+    puts "The voter list is invalid!"
+    puts "Total errors count: #{validation_result.total_errors_count}"
+  end
+rescue ElectionBuddy::Error => e
+  puts "Something went wrong: #{e.message}"
+end
+```
+
+The voter list validation can have two types of errors:
+
+1. **List-level errors**: Affect the entire voter list (e.g., missing required columns)
+2. **Line-level errors**: Affect specific lines in the voter list (e.g., invalid email format)
+
+#### List-Level Errors
+
+List-level errors can be retrieved using the `list_errors` method.
+
+```ruby
+if validation_result.list_errors.any?
+  puts "List-level errors:"
+  validation_result.list_errors.each do |list_error|
+    puts "Error message: #{list_error.error_message}"
+  end
+end
+```
+
+#### Line-Level Errors
+
+Line-level errors are paginated. You can specify the page number and the number of errors per page.
+If you don't specify the page number and the number of errors per page, the default values are 1 and 10, respectively.
+
+```ruby
+validation_result = client.voter_list.validation_result('ae0a1724-9791-4bb2-8331-6d4e55a9b7c8', page: 2, per_page: 10)
+line_errors = validation_result.line_errors
+puts "There is a total of #{line_errors.total} line-level errors."
+puts "The current page is #{line_errors.page}."
+puts "There are #{line_errors.per_page} errors per page."
+puts "There are #{line_errors.total_pages} pages in total."
+```
+
+PS: The `list_errors` object is always available, regardless of the line-level errors pagination.
+
+To iterate over the line-level errors, you can use the following code:
+
+```ruby
+if line_errors.any?
+  puts "Line-level errors for page #{line_errors.page}:"
+  line_errors.each do |line_error|
+    puts "Line identifier: #{line_error.voter_information_line_id}"
+    puts "Error messages:"
+    line_error.each do |line_error|
+      puts "Error messages #{line_error.error_messages}"
+    end
+  end
+end
+```
+
+### Possible API Errors
 
 The following errors may be raised by the API:
 
@@ -56,6 +164,17 @@ The following errors may be raised by the API:
 
 Each error will raise an `Error` exception with a message detailing the status code and the error message returned by the API.
 
+## Documentation
+
+The complete documentation for this gem is available at: https://electionbuddy.github.io/electionbuddy-ruby
+
+You can also generate the documentation locally using:
+
+```bash
+yard doc
+yard server
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/election_buddy/client.rb

@@ -1,15 +1,27 @@
 # frozen_string_literal: true
 
 module ElectionBuddy
+  # HTTP client for the ElectionBuddy API
+  #
+  # @example
+  #   client = Client.new(api_key: "your-api-key")
+  #   client.voter_list.validate(123)
+  #
   class Client
     BASE_URL = "https://secure.electionbuddy.com/api/v2"
 
-    def initialize(api_key, adapter: Faraday.default_adapter, stubs: nil)
-      @api_key = api_key
+    # @param api_key [String, nil] The API key for authentication (optional if configured globally)
+    # @param adapter [Object, nil] The HTTP client adapter to use (optional, defaults to Faraday's default adapter)
+    # @param stubs [Object, nil] Test stubs for the adapter (optional)
+    def initialize(api_key: nil, adapter: Faraday.default_adapter, stubs: nil)
+      @api_key = api_key || ElectionBuddy.configuration.api_key
       @adapter = adapter
       @stubs = stubs
     end
 
+    # Returns the voter list resource for handling voter-related operations
+    #
+    # @return [VoterListResource] The voter list resource
     def voter_list
       VoterListResource.new(connection)
     end

data/lib/election_buddy/configuration.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ElectionBuddy
+  # Configuration options for the ElectionBuddy client
+  class Configuration
+    # @return [String, nil] The API key used for authentication
+    attr_accessor :api_key
+  end
+end

data/lib/election_buddy/entities/importation.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ElectionBuddy
+  # Represents an importation operation for voter lists
+  #
+  # @example
+  #   importation = Importation.new(response)
+  #   if importation.done?
+  #     puts "Import successful: #{importation.identifier}"
+  #   else
+  #     puts "Import failed: #{importation.error}"
+  #   end
+  #
+  class Importation
+    # @param response [Hash] The API response containing importation details
+    def initialize(response)
+      @response = response
+    end
+
+    # Returns the identifier for this importation
+    #
+    # @return [String] The importation identifier or "Not Available"
+    def identifier
+      @response["importation_identifier"] || "Not Available"
+    end
+
+    # Checks if the importation completed successfully
+    #
+    # @return [Boolean] true if importation was successful, false otherwise
+    def done?
+      @response["error"].nil?
+    end
+
+    # Returns the error message if importation failed
+    #
+    # @return [String, nil] The formatted error message or nil if importation was successful
+    def error
+      return nil if done?
+
+      ErrorFormatter.format(@response["error"])
+    end
+  end
+end

data/lib/election_buddy/entities/validation/line_error.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ElectionBuddy
+  class Validation
+    # Represents a single line validation error
+    #
+    # @example
+    #   line_error = LineError.new({ "voter_information_line_id" => 123, "errors" => { "email" => ["is invalid"] } })
+    #   line_error.voter_information_line_id #=> 123
+    #   line_error.error_messages #=> ["email: is invalid"]
+    #
+    class LineError
+      # @return [Integer] The ID of the voter information line
+      attr_reader :voter_information_line_id
+
+      # @return [Hash] The errors hash containing categories and messages
+      attr_reader :errors
+
+      # @param line_error [Hash] The error hash containing line ID and errors
+      def initialize(line_error)
+        @voter_information_line_id = line_error["voter_information_line_id"]
+        @errors = line_error["errors"]
+      end
+
+      # Returns formatted error messages for each category
+      #
+      # @return [Array<String>] Array of formatted error messages
+      def error_messages
+        @errors.map do |(category, messages)|
+          "#{category}: #{messages.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/election_buddy/entities/validation/line_errors.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ElectionBuddy
+  class Validation
+    # Represents a collection of line-by-line validation errors
+    #
+    # @example
+    #   line_errors = LineErrors.new(response)
+    #   line_errors.total #=> 5
+    #   line_errors.total_pages #=> 1
+    #   line_errors.empty? #=> false
+    #
+    class LineErrors
+      include Enumerable
+
+      # @return [Integer] Total number of validation errors
+      attr_reader :total
+
+      # @return [Integer] Current page number
+      attr_reader :page
+
+      # @return [Integer] Number of items per page
+      attr_reader :per_page
+
+      # @param response [Hash] API response containing validation errors
+      def initialize(response)
+        @line_errors = response["voter_line_errors"]
+        @total = response["meta"]["total"]
+        @page = response["meta"]["page"]
+        @per_page = response["meta"]["per_page"]
+      end
+
+      # Calculates the total number of pages
+      #
+      # @return [Integer] Total number of pages
+      def total_pages
+        (total.to_f / per_page).ceil
+      end
+
+      # Iterates through each line error
+      #
+      # @return [Enumerator] Collection of line errors
+      def each(&block)
+        collection.each(&block)
+      end
+
+      # Checks if there are any line errors
+      #
+      # @return [Boolean] true if no errors exist, false otherwise
+      def empty?
+        collection.empty?
+      end
+
+      private
+
+      def collection
+        @collection ||= @line_errors.map { |line_error| LineError.new(line_error) }
+      end
+    end
+  end
+end

data/lib/election_buddy/entities/validation/list_error.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ElectionBuddy
+  class Validation
+    # Represents a single voter list validation error
+    #
+    # @example
+    #   error = ListError.new({ "email" => ["is invalid", "is required"] })
+    #   error.category #=> "email"
+    #   error.messages #=> ["is invalid", "is required"]
+    #   error.error_message #=> "email: is invalid, is required"
+    #
+    class ListError
+      # @return [Hash] The raw error data
+      attr_reader :error
+
+      # @return [String] The category of the error
+      attr_reader :category
+
+      # @return [Array<String>] The error messages
+      attr_reader :messages
+
+      # @param error [Hash] The error hash containing category and messages
+      def initialize(error)
+        @error = error
+        @category, @messages = error.first
+      end
+
+      # Returns a formatted error message
+      #
+      # @return [String] The formatted error message
+      def error_message
+        "#{category}: #{messages.join(", ")}"
+      end
+    end
+  end
+end

data/lib/election_buddy/entities/validation/list_errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ElectionBuddy
+  class Validation
+    # Represents a collection of voter list validation errors
+    #
+    # @example
+    #   list_errors = ListErrors.new(response)
+    #   list_errors.total #=> 2
+    #   list_errors.empty? #=> false
+    #
+    class ListErrors
+      include Enumerable
+
+      # @return [Integer] Total number of validation errors
+      attr_reader :total
+
+      # @param response [Hash] API response containing validation errors
+      def initialize(response)
+        @list_errors = response["voter_list_errors"]
+        @total = response["meta"]["total"]
+      end
+
+      # Iterates through each list error
+      #
+      # @return [Enumerator] Collection of list errors
+      def each(&block)
+        collection.each(&block)
+      end
+
+      # Checks if there are any list errors
+      #
+      # @return [Boolean] true if no errors exist, false otherwise
+      def empty?
+        collection.empty?
+      end
+
+      private
+
+      def collection
+        @collection ||= @list_errors
+                        .map { |category, messages| { category => messages } }
+                        .map { |list_error| ListError.new(list_error) }
+      end
+    end
+  end
+end

data/lib/election_buddy/entities/validation/result.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module ElectionBuddy
+  class Validation
+    class UnavailableTotalErrorsCount < ElectionBuddy::Error; end
+    class UnavailableValidStatus < ElectionBuddy::Error; end
+
+    Success = ->(data) { { success?: true, data: data } }
+    Failure = ->(error) { { success?: false, error: error } }
+    private_constant :Success, :Failure
+
+    # Represents the result of a validation operation
+    #
+    # @example Check if validation passed
+    #   result = Result.new(response)
+    #   result.valid? #=> true
+    #   result.total_errors_count #=> 0
+    #
+    # @example Handle validation errors
+    #   result = Result.new(response)
+    #   result.valid? #=> false
+    #   result.total_errors_count #=> 3
+    #   result.list_errors #=> #<ListErrors @total=1>
+    #   result.line_errors #=> #<LineErrors @total=2>
+    #
+    # @example Handle API failures
+    #   result = Result.new(response)
+    #   result.valid? #=> raises UnavailableValidStatus
+    #   result.total_errors_count #=> raises UnavailableTotalErrorsCount
+    #   result.failure_message #=> "API call has failed - Error: Validation: not found"
+    class Result
+      # Initializes a new validation result
+      #
+      # @param response [Hash] The raw response from the validation API
+      def initialize(response)
+        @result = process_response(response)
+      end
+
+      # Returns the list of validation errors related to the voter list
+      # @return [ListErrors, Array] List validation errors or empty array if validation failed
+      def list_errors
+        return [] unless success?
+
+        @list_errors ||= ListErrors.new(@result[:data].dig("results", "voter_list_validations"))
+      end
+
+      # Returns the line-by-line validation errors
+      # @return [LineErrors, Array] Line validation errors or empty array if validation failed
+      def line_errors
+        return [] unless success?
+
+        @line_errors ||= LineErrors.new(@result[:data].dig("results", "voter_lines_validation"))
+      end
+
+      # Returns the total count of all validation errors
+      #
+      # @return [Integer] Total number of validation errors
+      # @raise [UnavailableTotalErrorsCount] if the API call failed
+      def total_errors_count
+        raise UnavailableTotalErrorsCount, failure_message if failure?
+
+        list_errors.total + line_errors.total
+      end
+
+      # Indicates if the validation passed without errors
+      #
+      # @return [Boolean] true if validation passed, false otherwise
+      # @raise [UnavailableValidStatus] if the API call failed
+      def valid?
+        raise UnavailableValidStatus, failure_message if failure?
+
+        total_errors_count.zero?
+      end
+
+      # Returns the error message if validation failed
+      #
+      # @return [String, nil] The formatted error message or nil if successful
+      def failure_error
+        return if success?
+
+        ::ElectionBuddy::ErrorFormatter.format(@result[:error])
+      end
+
+      # Returns a user-friendly failure message
+      #
+      # @return [String, nil] The failure message or nil if successful
+      def failure_message
+        return if success?
+
+        "API call has failed - Error: #{failure_error}"
+      end
+
+      private
+
+      def success?
+        @result[:success?]
+      end
+
+      def failure?
+        !success?
+      end
+
+      def process_response(response)
+        if response["error"]
+          Failure.call(response["error"])
+        else
+          Success.call(response)
+        end
+      end
+    end
+  end
+end

data/lib/election_buddy/entities/validation.rb

@@ -1,19 +1,36 @@
 # frozen_string_literal: true
 
 module ElectionBuddy
+  # Represents a validation operation response from the ElectionBuddy API
+  # This class handles both successful and failed validation responses
+  #
+  # @example
+  #   validation = Validation.new(response_hash)
+  #   validation.done? #=> true/false
+  #
   class Validation
+    # @param response [Hash] The raw API response containing validation details
     def initialize(response)
       @response = response
     end
 
+    # Returns the unique identifier for this validation
+    #
+    # @return [String] The validation identifier or "Not available" if not present
     def identifier
       @response["validation_identifier"] || "Not available"
     end
 
+    # Checks if the validation completed successfully without errors
+    #
+    # @return [Boolean] true if validation completed without errors, false otherwise
     def done?
       @response["error"].nil?
     end
 
+    # Returns formatted error message if validation failed
+    #
+    # @return [String, nil] Formatted error message or nil if validation was successful
     def error
       return nil if done?
 

data/lib/election_buddy/error.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 module ElectionBuddy
+  # @api public
+  # Base error class for ElectionBuddy exceptions
+  #
+  # @example Raising a custom error
+  #   raise ElectionBuddy::Error, "Something went wrong"
+  #
+  # @since 0.1.0
   class Error < StandardError
   end
 end

data/lib/election_buddy/error_formatter.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
 module ElectionBuddy
+  # Formats error messages from hash responses
+  #
+  # @example
+  #   ErrorFormatter.format({ "email" => ["is invalid", "is required"] })
+  #   #=> "Email: is invalid, is required"
+  #
   class ErrorFormatter
+    # Formats error messages from a hash into a human-readable string
+    #
+    # @param error_hash [Hash, nil] Hash containing error keys and messages
+    # @return [String, nil] Formatted error message or nil if no errors
     def self.format(error_hash)
       return if error_hash.nil? || error_hash.empty?
 

data/lib/election_buddy/resource.rb

@@ -1,15 +1,37 @@
 # frozen_string_literal: true
 
 module ElectionBuddy
+  # Base class for API resources
+  #
+  # @example
+  #   class VoterListResource < Resource
+  #     def validate(vote_id)
+  #       post_request("/api/v2/votes/voters/validations", vote_id: vote_id)
+  #     end
+  #   end
+  #
   class Resource
+    # @param connection [Object] The HTTP client connection
     def initialize(connection)
       @connection = connection
     end
 
+    # Makes a GET request to the API
+    #
+    # @param url [String] The API endpoint URL
+    # @param params [Hash] Query parameters
+    # @param headers [Hash] Request headers
+    # @return [Hash] The API response
     def get_request(url, params = {}, headers = {}, &block)
       handle_response(@connection.get(url, params, headers, &block))
     end
 
+    # Makes a POST request to the API
+    #
+    # @param url [String] The API endpoint URL
+    # @param body [Hash] Request body parameters
+    # @param headers [Hash] Request headers
+    # @return [Hash] The API response
     def post_request(url, body = {}, headers = {}, &block)
       handle_response(@connection.post(url, body, headers, &block))
     end
@@ -17,7 +39,7 @@ module ElectionBuddy
     private
 
     def handle_response(response)
-      return response.body if response.success? || response.status == 422
+      return response.body if response.success? || [422, 423].include?(response.status)
 
       raise_error(response.status, ErrorFormatter.format(response.body))
     end

data/lib/election_buddy/resources/voter_list_resource.rb

@@ -1,11 +1,47 @@
 # frozen_string_literal: true
 
 module ElectionBuddy
+  # Handles voter list validation operations
+  #
+  # @example
+  #   resource = VoterListResource.new(client)
+  #   validation = resource.validate(123)
+  #   result = resource.get_validation_result(validation.identifier)
+  #
   class VoterListResource < Resource
+    # Imports voters for a given vote
+    #
+    # @param vote_id [Integer] The ID of the vote to import voters for
+    # @param voters [Array<Hash>] Array of voter data to import
+    # @param append_mode [Boolean] Whether to append voters to existing list (default: false)
+    # @return [Importation] The importation response
+    def import(vote_id, voters, append_mode: false)
+      response = post_request("/api/v2/votes/voters/importations", vote_id: vote_id.to_i, voters: voters, append_mode: append_mode)
+
+      Importation.new(response)
+    end
+
+    # Initiates a validation for a given vote
+    #
+    # @param vote_id [Integer] The ID of the vote to validate
+    # @return [Validation] The validation response
     def validate(vote_id)
       response = post_request("/api/v2/votes/voters/validations", vote_id: vote_id.to_i)
 
       Validation.new(response)
     end
+
+    # Retrieves the validation results
+    #
+    # @param identifier [String] The validation identifier
+    # @param page [Integer, nil] The page number for paginated results (optional, default: 1)
+    # @param per_page [Integer, nil] The number of items per page (optional, default: 10)
+    # @return [Validation::Result] The validation results
+    def get_validation_result(identifier, page: 1, per_page: 10)
+      params = { "identifier" => identifier, "page" => page, "per_page" => per_page }
+      response = get_request("/api/v2/votes/voters/validations", params)
+
+      Validation::Result.new(response)
+    end
   end
 end

data/lib/election_buddy/version.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
 module ElectionBuddy
-  VERSION = "0.2.0"
+  # Current version of ElectionBuddy gem
+  #
+  # @api public
+  # @return [String] the current version of the gem
+  # @example Get current version
+  #   ElectionBuddy::VERSION #=> "0.4.0"
+  VERSION = "0.4.0"
 end

data/lib/election_buddy.rb

@@ -10,7 +10,34 @@ require "election_buddy/error"
 require "election_buddy/resource"
 require "election_buddy/resources/voter_list_resource"
 require "election_buddy/entities/validation"
+require "election_buddy/entities/importation"
 require "election_buddy/error_formatter"
+require "election_buddy/configuration"
+require "election_buddy/entities/validation/result"
+require "election_buddy/entities/validation/line_error"
+require "election_buddy/entities/validation/line_errors"
+require "election_buddy/entities/validation/list_error"
+require "election_buddy/entities/validation/list_errors"
 
+# ElectionBuddy API client library
+#
+# @api public
+# @example Configure the client
+#   ElectionBuddy.configure do |config|
+#     config.api_key = 'your-api-key'
+#   end
 module ElectionBuddy
+  class << self
+    # @return [Configuration] Current configuration
+    attr_accessor :configuration
+
+    # Configures the ElectionBuddy client
+    #
+    # @yield [config] Configuration instance to be modified
+    # @yieldparam [Configuration] config The configuration instance
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: electionbuddy-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Alberto Rocha
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-11-07 00:00:00.000000000 Z
+date: 2024-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -35,13 +35,21 @@ extra_rdoc_files: []
 files:
 - ".devcontainer/devcontainer.json"
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/election_buddy.rb
 - lib/election_buddy/client.rb
+- lib/election_buddy/configuration.rb
+- lib/election_buddy/entities/importation.rb
 - lib/election_buddy/entities/validation.rb
+- lib/election_buddy/entities/validation/line_error.rb
+- lib/election_buddy/entities/validation/line_errors.rb
+- lib/election_buddy/entities/validation/list_error.rb
+- lib/election_buddy/entities/validation/list_errors.rb
+- lib/election_buddy/entities/validation/result.rb
 - lib/election_buddy/error.rb
 - lib/election_buddy/error_formatter.rb
 - lib/election_buddy/resource.rb
@@ -72,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.2.33
 signing_key: 
 specification_version: 4
 summary: Ruby SDK for the ElectionBuddy API.