electionbuddy-ruby 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4d7bab3a1ccbb73ba611b3f24efe2cb30f46f8971fbdfcc9f7199d4cd90a5d1
-  data.tar.gz: f7ad3cf9058cf3e87e8b270223b593e8a3a3703a34d0a72f8441ac6a6a1111e1
+  metadata.gz: 05e63dbc220f5455343b5a43e4a2fa3754c377f7cb56aceb133acddf3a09fe84
+  data.tar.gz: 57afed7e7acaaf77e7ba70a7afae1d1efd56e058d403bf5eed9904d7e546d1d2
 SHA512:
-  metadata.gz: fd1e47298c9ede0a03d6e2ff07be9118d7f41ccfacb1acf1635d55e06ddd63ea7309fa965fac97a5dc2ea1b8e20d0eed20714af0761390197d2389661456a734
-  data.tar.gz: 61e1aac0c642c65f791f4b1f93f7602cc3e34c4c94f3a5d4875e223b483703dc56521a5961199d5675123d5c93b16110107d64a89eed38c93d133c7c221f3ca0
+  metadata.gz: 39d9ac1b3891a72787f0c2a80603d2e824e769109c04f977f9a7ef810bd78a34c0dd4403356d7658b67db80462297e59f8040df8f9ee10e4f96658c6f65f8b7c
+  data.tar.gz: b6f5c57a45c8075f25c515efeddf23825db14d8c694bf4fa9b6f70b919501d66bd4dffa9639cc940a0a809a8d0739febdd83f06b378e0247591fc9e844ab95fc

data/.rubocop.yml

@@ -6,3 +6,19 @@ Style/StringLiterals:
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Naming/FileName:
+  Exclude:
+    - 'lib/electionbuddy-ruby.rb'
+
+Metrics/MethodLength:
+  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

@@ -1,5 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
+## [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
+
+### Added
+
+- Faraday as a runtime dependency
+- Debug as a development dependency
+- API call framework: resource-oriented design to structure and support API calls
+- Ability to validate the voter list of a given vote
+
+### Changed
+
+- Update README.md with usage instructions
+- Update .rubocop.yml with new rules
+
+### Fixed
+
+- Fix console startup issue caused by incorrect code reference
+
 ## [0.1.0] - 2024-10-29
 
 - Initial release
+
+[unreleased]: https://github.com/electionbuddy/electionbuddy-ruby/compare/v0.3.0...HEAD
+[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,24 +1,158 @@
-# Electionbuddy::Ruby
+# ElectionBuddy Ruby
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/electionbuddy/ruby`. To experiment with that code, run `bin/console` for an interactive prompt.
+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
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
-Install the gem and add to the application's Gemfile by executing:
+Install the gem and add it to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+    bundle add electionbuddy-ruby
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+    gem install electionbuddy-ruby
+
+Alternatively, add the gem to the Gemfile:
+
+```ruby
+gem 'electionbuddy-ruby'
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+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
+```
+
+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 Validation
+
+To validate a voter list, use the `voter_list.validate(vote_id)` method:
+
+```ruby
+validation = client.voter_list.validate(1)
+
+if validation.done?
+  puts "Validation completed successfully! Identifier: #{validation.identifier}"
+else
+  puts "Validation failed: #{validation.error}"
+end
+```
+
+### 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:
+
+- **400**: Malformed request.
+- **401**: Invalid authentication credentials.
+- **403**: Unauthorized.
+- **404**: Resource not found.
+- **429**: Your request exceeded the API rate limit.
+- **500**: We were unable to perform the request due to server-side problems.
+
+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
 
@@ -28,7 +162,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/electionbuddy-ruby.
+Bug reports and pull requests are welcome on GitHub at https://github.com/electionbuddy/electionbuddy-ruby.
 
 ## License
 

data/lib/election_buddy/client.rb

@@ -0,0 +1,40 @@
+# 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"
+
+    # @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
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(BASE_URL) do |conn|
+        conn.headers["authorization"] = @api_key
+        conn.request :json
+        conn.response :json, content_type: /\bjson$/
+        conn.adapter @adapter, @stubs
+      end
+    end
+  end
+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/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

@@ -0,0 +1,40 @@
+# 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?
+
+      ErrorFormatter.format(@response["error"])
+    end
+  end
+end

data/lib/election_buddy/error.rb

@@ -0,0 +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

@@ -0,0 +1,25 @@
+# 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?
+
+      error_hash.map do |key, value|
+        formatted_key = key.gsub("_", " ").split.map(&:capitalize).join(" ")
+        formatted_value = value.is_a?(Array) ? value.join(", ") : value
+        "#{formatted_key}: #{formatted_value}"
+      end.join(", ")
+    end
+  end
+end

data/lib/election_buddy/resource.rb

@@ -0,0 +1,70 @@
+# 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
+
+    private
+
+    def handle_response(response)
+      return response.body if response.success? || [422, 423].include?(response.status)
+
+      raise_error(response.status, ErrorFormatter.format(response.body))
+    end
+
+    def raise_error(status, formatted_error)
+      base_message = error_messages(status)
+      message = if formatted_error
+                  "Error #{status}: #{base_message} - #{formatted_error}."
+                else
+                  "Error #{status}: #{base_message}."
+                end
+
+      raise Error, message
+    end
+
+    def error_messages(status)
+      messages = {
+        400 => "Malformed request",
+        401 => "Invalid authentication credentials",
+        403 => "Unauthorized",
+        404 => "Resource not found",
+        429 => "Your request exceeded the API rate limit",
+        500 => "We were unable to perform the request due to server-side problems"
+      }
+      messages.fetch(status, "Unexpected status code.")
+    end
+  end
+end

data/lib/election_buddy/resources/voter_list_resource.rb

@@ -0,0 +1,35 @@
+# 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
+    # 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

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

data/lib/election_buddy.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/middleware"
+require "json"
+
+require "election_buddy/version"
+require "election_buddy/client"
+require "election_buddy/error"
+require "election_buddy/resource"
+require "election_buddy/resources/voter_list_resource"
+require "election_buddy/entities/validation"
+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

data/lib/electionbuddy-ruby.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "election_buddy"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: electionbuddy-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Alberto Rocha
@@ -9,8 +9,22 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-10-29 00:00:00.000000000 Z
-dependencies: []
+date: 2024-11-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.12'
 description: This gem provides a Ruby SDK for easy interaction with the ElectionBuddy
   API
 email:
@@ -21,12 +35,26 @@ extra_rdoc_files: []
 files:
 - ".devcontainer/devcontainer.json"
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- lib/electionbuddy/ruby.rb
-- lib/electionbuddy/ruby/version.rb
+- lib/election_buddy.rb
+- lib/election_buddy/client.rb
+- lib/election_buddy/configuration.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
+- lib/election_buddy/resources/voter_list_resource.rb
+- lib/election_buddy/version.rb
+- lib/electionbuddy-ruby.rb
 - sig/electionbuddy/ruby.rbs
 homepage: https://github.com/electionbuddy/electionbuddy-ruby
 licenses:

data/lib/electionbuddy/ruby/version.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module Electionbuddy
-  module Ruby
-    VERSION = "0.1.0"
-  end
-end

data/lib/electionbuddy/ruby.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "ruby/version"
-
-module Electionbuddy
-  module Ruby
-    class Error < StandardError; end
-    # Your code goes here...
-  end
-end