verifalia 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 13ecdf0dda8a8b5eed02d2fbc681f57f46905e4e
-  data.tar.gz: 45a067871869dacd52fce6649d6ecf6f244a71e8
+SHA256:
+  metadata.gz: 14650c8b1a2409f0c037e1e5348c445434fcf22930bb465f78e548c7fb42b4ca
+  data.tar.gz: ceb6552a4935d73b4488558d8e11ae1de15de1b740a92811eb9240984497e446
 SHA512:
-  metadata.gz: fc7beb23842a872e087cfc3e44af72cef66e67fbc4f36a303610fe39185cc13afbc0bad27370fb65fdb5abaf3e274b18d4b2c7364615f2c33c0f6b5fdd32d633
-  data.tar.gz: 7676bc471f56549a75b4e7303341500c69b86f091567b0edfa7f7a6dcca4ab0443e5aba2ac5273c3a6c2bd60ab72d5433ddc2ece045aa5e8ea50cf3b2ba1a6bf
+  metadata.gz: 346075e83859afee3fa6c24b696d889973634eef9bab43febf7c60742b992f08d80035457c6c334f06e8995ac78016ff5b7300cd179a6299804755650fa18691
+  data.tar.gz: 8e5b6be8fe6528bd04b605ff61e39289017a114f31322229595bfd90964f1d6ac596d1aeb0a2eac4317752e367002d68f278a8aae0519e3fc4797beb6a6d8130

data/Gemfile

@@ -1,9 +1,9 @@
-source 'https://rubygems.org'
+# frozen_string_literal: true
+
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in verifalia.gemspec
 gemspec
 
-group :test do
-  gem 'rspec', '~> 3.0'
-  gem 'coveralls', require: false
-end
+gem "rake", "~> 13.0"
+gem "rubocop", "~> 1.21"

data/LICENSE

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2014 Verifalia
+Copyright (c) 2014-2023 Cobisi Research - https://verifalia.com/
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,5 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
+SOFTWARE.

data/README.md

@@ -1,121 +1,367 @@
-[![Circle CI](https://circleci.com/gh/verifalia/verifalia-ruby-sdk.svg?style=shield)](https://circleci.com/gh/verifalia/verifalia-ruby-sdk)
+![Verifalia API](https://img.shields.io/badge/Verifalia%20API-v2.4-green)
 [![Gem Version](https://badge.fury.io/rb/verifalia.svg)](https://badge.fury.io/rb/verifalia)
-[![Dependency Status](https://gemnasium.com/verifalia/verifalia-ruby-sdk.svg)](https://gemnasium.com/verifalia/verifalia-ruby-sdk)
-[![Code Climate](https://codeclimate.com/github/verifalia/verifalia-ruby-sdk/badges/gpa.svg)](https://codeclimate.com/github/verifalia/verifalia-ruby-sdk)
-[![Coverage Status](https://coveralls.io/repos/verifalia/verifalia-ruby-sdk/badge.svg?branch=master&service=github)](https://coveralls.io/github/verifalia/verifalia-ruby-sdk?branch=master)
-[![Inline docs](http://inch-ci.org/github/verifalia/verifalia-ruby-sdk.svg?branch=master)](http://inch-ci.org/github/verifalia/verifalia-ruby-sdk)
 
-# Verifalia RESTful API - Ruby gem
+# Verifalia - Ruby gem
 
-Verifalia provides a simple HTTPS-based API for validating email addresses and checking whether or not they are deliverable;
-this Ruby gem allows to communicate with the Verifalia API, scrubbing lists of email addresses in a couple of lines of code.
-To learn more about Verifalia, please visit http://verifalia.com
+[Verifalia](https://verifalia.com/) provides a simple HTTPS-based API for **validating email addresses in
+real-time** and checking whether they are deliverable or not; this SDK library integrates with Verifalia
+and allows to [verify email addresses](https://verifalia.com/) in **Ruby 2.6.0 or higher**.
 
-## Installation
+To learn more about Verifalia please see [https://verifalia.com](https://verifalia.com/)
 
-Add this line to your application's Gemfile:
+## Table of contents
 
-    gem 'verifalia'
+- [Adding Verifalia to your Ruby app](#adding-verifalia-to-your-ruby-app)
+  * [Authentication](#authentication)
+    + [Authenticating via X.509 client certificate (TLS mutual authentication)](#authenticating-via-x509-client-certificate--tls-mutual-authentication-)
+- [Validating email addresses](#validating-email-addresses)
+  * [How to validate an email address](#how-to-validate-an-email-address)
+  * [How to validate a list of email addresses](#how-to-validate-a-list-of-email-addresses)
+  * [Processing options](#processing-options)
+    + [Quality level](#quality-level)
+    + [Deduplication mode](#deduplication-mode)
+    + [Data retention](#data-retention)
+  * [Wait options](#wait-options)
+    + [Avoid waiting](#avoid-waiting)
+    + [Progress tracking](#progress-tracking)
+  * [Completion callbacks](#completion-callbacks)
+  * [Retrieving jobs](#retrieving-jobs)
+  * [Exporting email verification results in different output formats](#exporting-email-verification-results-in-different-output-formats)
+  * [Don't forget to clean up, when you are done](#don-t-forget-to-clean-up--when-you-are-done)
+- [Managing credits](#managing-credits)
+  * [Getting the credits balance](#getting-the-credits-balance)
+- [Changelog / What's new](#changelog---what-s-new)
 
-And then execute:
+## Adding Verifalia to your Ruby app
 
-    $ bundle
+To install using [Bundler](https://bundler.io/) grab the latest version:
 
-Or install it yourself as:
+```ruby
+gem 'verifalia'
+```
+
+To manually install `verifalia` via Rubygems simply run `gem install`:
+
+```ruby
+gem install verifalia
+```
+
+### Authentication ###
 
-    $ gem install verifalia
+First things first: authentication to the Verifalia API is performed by way of either the credentials
+of your root Verifalia account or of one of its users (previously known as sub-accounts): if you don't
+have a Verifalia account, just [register for a free one](https://verifalia.com/sign-up/free).
+For security reasons, it is always advisable to [create and use a dedicated user](https://verifalia.com/client-area#/users/new)
+for accessing the API, as doing so will allow to assign only the specific needed permissions to it.
 
-## Getting Started With REST ##
+Learn more about authenticating to the Verifalia API at [https://verifalia.com/developers#authentication](https://verifalia.com/developers#authentication)
 
-### Setup Work ###
+Once you have your Verifalia credentials at hand, use them while creating a new instance of the
+`Verifalia::Client` class, which will be the starting point to every other operation against the
+Verifalia API: the supplied credentials will be automatically provided to the API using the HTTP
+Basic Auth method.
 
 ```ruby
 require 'verifalia'
 
-# put your own credentials here (grabbed from your Verifalia client account area)
-account_sid = 'YOUR-ACCOUNT-SID'
-auth_token = 'YOUR-AUTH-TOKEN'
+# ...
 
-# set up a client to talk to the Verifalia REST API
-@client = Verifalia::REST::Client.new account_sid, auth_token
+verifalia = Verifalia::Client.new username: 'your-username', password: 'your-password'
+```
 
-# alternatively, you can preconfigure the client like so
-Verifalia.configure do |config|
-  config.account_sid = account_sid
-  config.auth_token = auth_token
-end
+#### Authenticating via X.509 client certificate (TLS mutual authentication)
+
+In addition to the HTTP Basic Auth method, this SDK also supports using a cryptographic X.509 client
+certificate to authenticate against the Verifalia API, through the TLS protocol. This method, also
+called mutual TLS authentication (mTLS) or two-way authentication, offers the highest degree of
+security, as only a cryptographically-derived key (and not the actual credentials) is sent over
+the wire on each request.
+
+```ruby
+# my-cert.pem contains both the private and public (certificate) key, but
+# you may specify different files if needed. 
+
+verifalia = Verifalia::Client.new ssl_client_cert: './my-cert.pem',
+                                  ssl_client_key: './my-cert.pem'
+```
+
+See [how to create a self-signed X.509 client certificate for TLS mutual authentication](https://verifalia.com/help/sub-accounts/how-to-create-self-signed-client-certificate-for-tls-mutual-authentication)
+on the Verifalia website, for more information on creating your own certificates for the Verifalia API.
+
+## Validating email addresses ##
+
+Every operation related to verifying / validating email addresses is performed through the
+`email_validations` property exposed by the `Verifalia::Client` instance you created above, which
+exposes some useful functions: in the next few paragraphs we are looking at the most used ones, so
+it is strongly advisable to explore the library and look at the embedded help for other opportunities.
+
+**The library automatically waits for the completion of email verification jobs**: if needed, it is possible
+to adjust the wait options and have more control over the entire underlying polling process. Please refer to
+the [Wait options](#wait-options) section below for additional details.
+
+### How to validate an email address ###
+
+To validate an email address from a Ruby application you can invoke the `submit()` method: it
+accepts one or more email addresses and any eventual verification options you wish to pass to Verifalia,
+including the expected results quality, deduplication preferences, processing priority.
 
-# and then you can create a new client without parameters
-@client = Verifalia::REST::Client.new
+In the following example, we verify an email address with this library, using the default options:
 
+```ruby
+job = verifalia.email_validations.submit 'batman@gmail.com'
+
+# At this point the address has been validated: let's print its validation
+# result to the console.
+
+entry = job.entries[0]
+puts "Classification: #{entry.classification} (status: #{entry.status})"
+
+# Classification: Deliverable (status: Success)
 ```
 
-### Email Validations ###
+### How to validate a list of email addresses ###
+
+To verify a list of email addresses - instead of a single address - it is possible to pass an array of strings with the
+emails to verify to the `submit()` method; here is an example showing how to verify an array with some
+email addresses:
 
 ```ruby
-##from scratch
-emails = ['alice@example.com', 'bob@example.net']
-if (unique_id = @client.email_validations.verify(emails))
-  #response is an hash with all the values returned
-  response = @client.email_validations.query
-  @client.email_validations.destroy
-else
-  #error is HTTP status code in symbol (:bad_request)
-  error = @client.email_validations.error
+job = verifalia.email_validations.submit ['batman@gmail.com', 'samantha42@yahoo.it']
+
+job.entries.each do |entry|
+  puts "#{entry.input_data} => #{entry.classification} (#{entry.status})"
 end
 
-##with additional email data
+# batman@gmail.com => Deliverable (Success)
+# samantha42@yahoo.it => Deliverable (Success)
+```
+
+### Processing options
+
+While submitting one or more email addresses for verification, it is possible to specify several
+options which affect the behavior of the Verifalia processing engine as well as the verification flow
+from the API consumer standpoint.
+
+#### Quality level
+
+Verifalia offers three distinct quality levels - namely, _Standard_, _High_ and _Extreme_  - which rule out how the email verification engine should
+deal with temporary undeliverability issues, with slower mail exchangers and other potentially transient
+problems which can affect the quality of the verification results. The `submit()` method accepts a `quality` keyword
+argument which allows
+to specify the desired quality level; here is an example showing how to verify an email address using
+the _High_ quality level:
+
+```ruby
+job = verifalia.email_validations.submit 'batman@gmail.com', quality: 'High'
+```
+
+#### Deduplication mode
+
+While accepting multiple email addresses at once, the `submit()` method allows to specify how to
+deal with duplicated entries pertaining to the same input set; Verifalia supports a _Safe_ deduplication
+mode, which strongly adheres to the old IETF standards, and a _Relaxed_ mode which is more in line with
+what can be found in the majority of today's mail exchangers configurations.
+
+In the next example, we show how to import and verify a list of email addresses and mark duplicated
+entries using the _Relaxed_ deduplication mode:
+
+```ruby
 emails = [
-    { inputData: 'alice@example.com', custom: 'custom data' }, #view verifalia API documentation
-    { inputData: 'bob@example.net', custom: 'custom data' } #view verifalia API documentation
-  ]
-if (unique_id = @client.email_validations.verify(emails))
-  #response is an hash with all the values returned
-  response = @client.email_validations.query
-  @client.email_validations.destroy
-else
-  #error is HTTP status code in symbol (:bad_request)
-  error = @client.email_validations.error
+  'batman@gmail.com',
+  'steve.vai@best.music',
+  'samantha42@yahoo.it'
+]
+
+job = verifalia.email_validations.submit entries, deduplication: 'Relaxed'
+```
+
+#### Data retention
+
+Verifalia automatically deletes completed email verification jobs according to the data retention
+policy defined at the account level, which can be eventually overridden at the user level: one can
+use the [Verifalia clients area](https://verifalia.com/client-area) to configure these settings.
+
+It is also possible to specify a per-job data retention policy which govern the time to live of a submitted
+email verification job; to do that, provide the `submit()` method with the keyword argument `retention`
+set according to the `dd.hh:MM:ss` format, with the `dd.` part being optional.
+
+Here is how, for instance, one can set a data retention policy of 10 minutes while verifying
+an email address:
+
+```ruby
+job = verifalia.email_validations.submit 'batman@gmail.com', retention: '0:10:0'
+```
+
+### Wait options
+
+By default, the `submit()` method submits an email verification job to Verifalia and waits
+for its completion; the entire process may require some time to complete depending on the plan of the
+Verifalia account, the number of email addresses the submission contains, the specified quality level
+and other network factors including the latency of the mail exchangers under test.
+
+In waiting for the completion of a given email verification job, the library automatically polls the
+underlying Verifalia API until the results are ready; by default, it tries to take advantage of the long
+polling mode introduced with the Verifalia API v2.4, which allows to minimize the number of requests
+and get the verification results faster.
+
+#### Avoid waiting
+
+In certain scenarios (in a microservice architecture, for example), however, it may preferable to avoid
+waiting for a job completion and ask the Verifalia API, instead, to just queue it: in that case, the library
+would just return the job overview (and not its verification results) and it will be necessary to retrieve
+the verification results using the `get()` method.
+
+To do that, it is possible to specify the `Verifalia::EmailValidations::WaitOptions.no_wait` as the value
+for the `wait_options` keyword argument of the `submit()` method, as shown in the next example:
+
+```ruby
+wait_options = Verifalia::EmailValidations::WaitOptions.no_wait
+job = verifalia.email_validations.submit 'elon.musk@tesla.com', wait_options: wait_options
+
+puts "Status: #{job.overview.status}"
+# Status: InProgress
+```
+
+#### Progress tracking
+
+For jobs with a large number of email addresses, it could be useful to track progress as they are processed
+by the Verifalia email verification engine; to do that, it is possible to create an instance of the
+`Verifalia::EmailValidations::WaitOptions` class and provide a lambda which eventually receives progress notifications through the
+`progress` property.
+
+Here is how to define a progress notification handler which displays the progress percentage of a submitted
+job to the console window:
+
+```ruby
+WaitOptions = Verifalia::EmailValidations::WaitOptions
+
+progress = ->(overview) do
+  puts "Progress: #{(overview.progress&.percentage || 0) * 100}%..."
 end
 
-##with additional options data
+wait_options = WaitOptions.new 30 * 1000, 30 * 1000, progress: progress
+
 emails = [
-    { inputData: 'alice@example.com', custom: 'custom data' }, #view verifalia API documentation
-    { inputData: 'bob@example.net', custom: 'custom data' } #view verifalia API documentation
-  ]
-options = { #view verifalia API documentation
-  quality: 'high',
-  priority: 100,
-  deduplication: 'safe'
-}
-
-if (unique_id = @client.email_validations.verify(emails, options))
-  #response is an hash with all the values returned
-  response = @client.email_validations.query
-  @client.email_validations.destroy #destroy the job on the Verifalia server
-else
-  #error is HTTP status code in symbol (:bad_request)
-  error = @client.email_validations.error
-end
+  'alice@example.com',
+  'bob@example.net',
+  'charlie@example.org'
+]
+
+job = verifalia.email_validations.submit emails, wait_options: wait_options
+```
+
+### Completion callbacks
 
-#you can wait for job completion using options on query
-response = @client.email_validations.query(wait_for_completion: true, completion_max_retry: 2, completion_interval: 1)
+Along with each email validation job, it is possible to specify an URL which
+Verifalia will invoke (POST) once the job completes: this URL must use the HTTPS or HTTP
+scheme and be publicly accessible over the Internet.
+To learn more about completion callbacks, please see https://verifalia.com/developers#email-validations-completion-callback
 
+To specify a completion callback URL, specify the `completion_callback` keyword argument while
+invoking the `submit()` method, as shown in the example below:
+
+```ruby
+verifalia.email_validations.submit 'batman@gmail.com',
+                                   completion_callback: {
+                                     'url' => 'https://your-website-here/foo/bar'
+                                   }
+```
 
-##with previous unique id
-unique_id = "example-example"
+Note that completion callbacks are invoked asynchronously and it could take up to
+several seconds for your callback URL to get invoked.
+
+### Retrieving jobs
+
+It is possible to retrieve a job through the `get()` method, which
+returns, respectively, a `Verifalia::EmailValidations::Job` instance for the desired
+email verification job. While doing that, the library automatically waits for the completion of
+the job, and it is possible to adjust this behavior by passing to the aforementioned method
+a `wait_options` keyword argument, in the exactly same fashion as described for the `submit()` method;
+please see the [Wait options](#wait-options) section for additional details.
+
+Here is an example showing how to retrieve a job, given its identifier:
+
+```ruby
+job_id = 'ec415ecd-0d0b-49c4-a5f0-f35c182e40ea'
+job = verifalia.email_validations.get job_id
+```
 
-#query job  
-response = @client.email_validations(unique_id: unique_id).query
+### Exporting email verification results in different output formats
 
-#delete job
-@client.email_validations(unique_id: unique_id).destroy
+This library also allows to export the entries of a completed email validation
+job in different output formats through the `export()` method, with the goal of
+generating a human-readable representation of the verification results.
 
-# checking job status
-if @client.email_validations(unique_id: unique_id).completed?
-  response = @client.email_validations(unique_id: unique_id).query
+> **WARNING**: While the output schema (columns / labels / data format) is fairly
+> complete, you should always consider it as subject to change: use the `get()`
+> method instead if you need to rely on a stable output schema.
+
+Here is an example showing how to export a given email verification job as an
+Excel (xslx) file:
+
+```ruby
+job_id = 'ec415ecd-0d0b-49c4-a5f0-f35c182e40ea'
+format = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+
+data = verifalia.email_validations.export job_id, format
+
+File.open('./export.xlsx', 'wb') do |fp|
+  fp.write(data)
 end
+```
+
+### Don't forget to clean up, when you are done
 
-#checking account_balance. Remember to enable this feature in Verifalia dashboard or you get a :forbidden error
-@client.account_balance.balance
+Verifalia automatically deletes completed jobs after a configurable
+data-retention policy (see the related section) but it is strongly advisable that
+you delete your completed jobs as soon as possible, for privacy and security reasons.
+To do that, you can invoke the `delete()` method passing the job Id you wish to get rid of:
+
+```ruby
+verifalia.email_validations.delete job_id
 ```
+
+Once deleted, a job is gone and there is no way to retrieve its email validation results.
+
+## Managing credits ##
+
+To manage the Verifalia credits for your account you can use the `credits` property exposed
+by the `Verifalia::Client` instance created above. Like for the previous topic, in the next
+few paragraphs we are looking at the most used operations, so it is strongly advisable to
+explore the library and look at the embedded documentation for other opportunities.
+
+### Getting the credits balance ###
+
+One of the most common tasks you may need to perform on your account is retrieving the available
+number of free daily credits and credit packs. To do that, you can use the `get_balance()` method,
+which returns a `Verifalia::Credits::Balance` object, as shown in the next example:
+
+```ruby
+balance = verifalia.credits.get_balance
+
+puts "Credit packs: #{balance.credit_packs}"
+puts "Free daily credits: #{balance.free_credits} (will reset in #{balance.free_credits_reset_in})"
+
+# Credit packs: 956.332
+# Free daily credits: 128.66 (will reset in 09:08:23)
+```
+
+To add credit packs to your Verifalia account visit [https://verifalia.com/client-area#/credits/add](https://verifalia.com/client-area#/credits/add).
+
+## Changelog / What's new
+
+This section lists the changelog for the current major version of the library: for older versions,
+please see the [project releases](https://github.com/verifalia/verifalia-ruby-sdk/releases).
+
+### v2.0
+
+Released on March 12<sup>th</sup>, 2023
+
+- Added support for API v2.4
+- Added support for new completion callback options
+- Added support for specifying a custom wait time while submitting and retrieving email verification jobs
+- Added support for exporting completed email verification jobs in different output formats (CSV, Excel, Excel 97-2003)
+- Breaking change: the default job submission and retrieval behavior is now to wait for the completion
+  of jobs (but it is possible to change that through the new `WaitOptions` class)
+- Bumped dependencies
+- Improved documentation

data/Rakefile

@@ -1,5 +1,9 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 
+task default: %i[spec rubocop]
+
 desc "Open an irb session preloaded with this library"
 task :console do
   sh "irb -rubygems -I lib -r verifalia.rb"

data/lib/verifalia/client.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'openssl/x509'
+require_relative './rest/client'
+
+module Verifalia
+  # HTTPS-based REST client for Verifalia.
+  class Client
+    # The version of the Verifalia SDK for Ruby.
+    VERSION = '2.0.0'
+
+    # Allows to verify email addresses and manage email verification jobs using the Verifalia service.
+    attr_reader :email_validations
+
+    # Manages credit packs, daily free credits and usage consumption for the Verifalia account.
+    attr_reader :credits
+
+    # Initializes a new HTTPS-based REST client for Verifalia with the specified options.
+    #
+    # While authenticating with your Verifalia main account credentials is possible, it is strongly advised to create
+    # one or more users (formerly known as sub-accounts) with just the required permissions, for improved security.
+    # To create a new user or manage existing ones, please visit 'https://verifalia.com/client-area#/users'
+    #
+    # @param [nil] authenticator A custom authenticator the client will use to authenticate against the Verifalia API.
+    # @param [nil] username The user-name used to authenticate against the Verifalia API using basic auth.
+    # @param [nil] password The password used to authenticate against the Verifalia API using basic auth.
+    # @param [nil] ssl_client_cert The X.509 client certificate used to authenticate against the Verifalia API using mutual TLS authentication. Available to premium Verifalia plans only.
+    # @param [nil] ssl_client_key The private key used to authenticate against the Verifalia API using mutual TLS authentication. Available to premium Verifalia plans only.
+    # @param [nil] base_urls Alternative base URLs to use while connecting against the Verifalia API.
+    # @param [nil] logger A logger where to write diagnostics messages, useful while debugging.
+    def initialize(authenticator: nil, username: nil, password: nil, ssl_client_cert: nil, ssl_client_key: nil, base_urls: nil, logger: nil)
+      @base_urls = base_urls
+
+      # Initialize the authenticator this client will use while connecting to the Verifalia API
+
+      if !authenticator.nil?
+        @authenticator = authenticator
+      elsif !username.nil?
+        @authenticator = Verifalia::Security::UsernamePasswordAuthenticator.new(username, password)
+      elsif !ssl_client_cert.nil?
+        @authenticator = Verifalia::Security::CertificateAuthenticator.new(ssl_client_cert, ssl_client_key)
+        @base_urls ||= Verifalia::Rest::BASE_CCA_URLS
+      else
+        raise ArgumentError, 'Username is nil and no other authentication method was specified: please visit https://verifalia.com/client-area to set up a new user, if you don\'t have one.'
+      end
+
+      @base_urls ||= Verifalia::Rest::BASE_URLS
+      @rest_client = Verifalia::Rest::Client.new(@authenticator,
+                                                 "verifalia-rest-client/ruby/#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}",
+                                                 @base_urls)
+
+      @rest_client.logger = logger
+
+      # Initialize the underlying resource clients
+
+      @email_validations = Verifalia::EmailValidations::Client.new(@rest_client)
+      @credits = Verifalia::Credits::Client.new(@rest_client)
+    end
+  end
+end

data/lib/verifalia/credits/balance.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Verifalia
+  module Credits
+    # The credits balance for the Verifalia account.
+    class Balance
+      # The number of credit packs (that is, non-expiring credits) available for the account.
+      attr_reader :credit_packs
+
+      # The number of free daily credits of the account, where available.
+      attr_reader :free_credits
+
+      # A string representing the amount of time before the daily credits expire, where available, expressed in the form +hh:mm:ss+.
+      attr_reader :free_credits_reset_in
+
+      def initialize(credit_packs, free_credits, free_credits_reset_in)
+        @credit_packs = credit_packs
+        @free_credits = free_credits
+        @free_credits_reset_in = free_credits_reset_in
+      end
+
+      # Parse a Balance from a JSON string.
+      def self.from_json(data)
+        Balance.new data['creditPacks'],
+                    data['freeCredits'],
+                    data['freeCreditsResetIn']
+      end
+    end
+  end
+end

data/lib/verifalia/credits/client.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'balance'
+
+module Verifalia
+  module Credits
+    # Manages credit packs, daily free credits and usage consumption for the Verifalia account.
+    class Client
+      def initialize(rest_client)
+        @rest_client = rest_client
+      end
+
+      # Returns the current credits balance for the Verifalia account.
+      # @return [Verifalia::Credits::Balance] The account balance.
+      def get_balance
+        response = @rest_client.invoke 'get',
+                                       'credits/balance'
+
+        return Balance.from_json(JSON.parse(response.body)) if response.status == 200
+
+        raise "Unexpected HTTP response: #{response.status} #{response.body}"
+      end
+    end
+  end
+end