neverbounce-api 1.0.0

data/.travis.yml

@@ -0,0 +1,27 @@
+
+language: ruby
+
+env:
+  global:
+    - CC_TEST_REPORTER_ID=9300cb7898e254e78099399acbb2796471fde0e5c1873899273a583d56c9d740
+
+install:
+  - bundle install --path ~/bundle
+
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+
+script:
+  - bundle exec rspec
+
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT
+
+rvm:
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4

data/.yardopts

@@ -0,0 +1,2 @@
+
+--private

data/Gemfile

@@ -0,0 +1,17 @@
+
+source "https://rubygems.org"
+
+# Self.
+gem "neverbounce-api", path: Pathname(__dir__).realpath
+
+group :development do
+  # Code coverage report.
+  gem "simplecov"
+
+  # RSpec.
+  gem "rspec"
+
+  # YARD and friends.
+  gem "redcarpet"
+  gem "yard"
+end

data/Gemfile.lock

@@ -0,0 +1,48 @@
+PATH
+  remote: .
+  specs:
+    neverbounce-api (1.0.0)
+      httparty (~> 0.15)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.3)
+    docile (1.1.5)
+    httparty (0.15.6)
+      multi_xml (>= 0.5.2)
+    json (2.1.0)
+    multi_xml (0.6.0)
+    redcarpet (3.4.0)
+    rspec (3.6.0)
+      rspec-core (~> 3.6.0)
+      rspec-expectations (~> 3.6.0)
+      rspec-mocks (~> 3.6.0)
+    rspec-core (3.6.0)
+      rspec-support (~> 3.6.0)
+    rspec-expectations (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-mocks (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-support (3.6.0)
+    simplecov (0.15.0)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    yard (0.9.9)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  neverbounce-api!
+  redcarpet
+  rspec
+  simplecov
+  yard
+
+BUNDLED WITH
+   1.15.3

data/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2017 NeverBounce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 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.

data/README.md

@@ -0,0 +1,235 @@
+
+<p align="center"><img src="https://neverbounce-marketing.s3.amazonaws.com/neverbounce_color_600px.png"></p>
+
+<p align="center">
+  <a href="https://travis-ci.org/NeverBounce/NeverBounceApi-Ruby"><img src="https://travis-ci.org/NeverBounce/NeverBounceApi-Ruby.svg" alt="Build Status"></a>
+  <a href="https://codeclimate.com/github/NeverBounce/NeverBounceApi-Ruby/coverage"><img src="https://codeclimate.com/github/NeverBounce/NeverBounceApi-Ruby/badges/coverage.svg" /></a>
+  <a href="https://codeclimate.com/github/NeverBounce/NeverBounceApi-Ruby"><img src="https://codeclimate.com/github/NeverBounce/NeverBounceApi-Ruby/badges/gpa.svg" /></a>
+</p>
+
+NeverBounceApi-Ruby
+===================
+
+This is the official NeverBounce V4 API for Ruby. See also:
+
+* Our full RubyDoc documentation: http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby.
+* Our full REST API documentation: https://developers.neverbounce.com/v4.0/.
+
+## Installation
+
+In your `Gemfile`, add:
+
+```ruby
+gem "neverbounce-api", git: "https://github.com/NeverBounce/NeverBounceApi-Ruby.git"
+```
+
+Install bundle:
+
+```sh
+$ bundle install
+```
+
+In your Ruby code, do a:
+
+```ruby
+require "neverbounce"
+```
+
+## Usage
+
+To talk to the API, create a `Client` object and call one of its request methods.
+For example, let's get account info:
+
+```ruby
+client = NeverBounce::API::Client.new(api_key: "key123abc")   # Insert YOUR key here.
+resp = client.account_info
+
+if resp.ok?
+  puts "Free credits used: #{resp.credits_info.free_credits_used}"
+  puts "Free credits remaining: #{resp.credits_info.free_credits_remaining}"
+else
+  # This is a `Response::ErrorMessage`.
+  puts "Error: #{resp.status}: #{resp.message}"
+end
+```
+
+Now, let's check a single e-mail:
+
+```ruby
+resp = client.single_check(email: "support@neverbounce.com")
+if resp.ok?
+  puts "Result: #{resp.result}"
+  puts "Flags: #{resp.flags.join(' ')}"
+else
+  puts "Error: #{resp.status}: #{resp.message}"
+end
+```
+
+### Error handling
+
+Our API library raises subclasses of `API::Error` for higher-level errors and subclasses of `StandardError` in all other cases. This wrapper guarantees that you catch all errors from the API library:
+
+```ruby
+begin
+  client = NeverBounce::API::Client.new(...)
+  resp = client.jobs_create(...)
+  ...
+rescue => e
+  # Log the error with full backtrace.
+end
+```
+
+If you're running a background job, it's generally better to **log the full backtrace** in case you encounter unexpected server behaviour or something like that.
+
+## Client requests
+
+This a is complete list of requests supported by `API::Client`.
+
+### Get account information
+
+```ruby
+resp = client.account_info
+```
+
+See also: [method](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Client.html#account_info-instance_method), [REST](https://developers.neverbounce.com/v4.0/reference#account-info).
+
+### Check a single address
+
+```ruby
+resp = client.single_check(email: "alice@isp.com")
+resp = client.single_check(email: "alice@isp.com", address_info: true, credits_info: true, timeout: 3)
+```
+
+See also: [method](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Client.html#single_check-instance_method), [REST](https://developers.neverbounce.com/v4.0/reference#single-check).
+
+### Create a bulk job
+
+```ruby
+resp = client.jobs_create(supplied_input: [["alice@isp.com", "Alice Roberts"], ["bob.smith@gmail.com", "Bob Smith"]])
+resp = client.jobs_create(remote_input: "http://isp.com/emails.csv")
+resp = client.jobs_create(remote_input: "http://isp.com/emails.csv", filename: "emails.csv", run_sample: true)
+resp = client.jobs_create(remote_input: "http://isp.com/emails.csv", filename: "emails.csv", auto_start: true)
+```
+
+See also: [method](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Client.html#jobs_create-instance_method), [REST](https://developers.neverbounce.com/v4.0/reference#jobs-create).
+
+### Get bulk job status
+
+```ruby
+resp = client.jobs_status(job_id: 123)
+```
+
+See also: [method](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Client.html#jobs_status-instance_method), [REST](https://developers.neverbounce.com/v4.0/reference#jobs-status).
+
+### Get bulk job results
+
+```ruby
+resp = client.jobs_results(job_id: 123)
+resp = client.jobs_results(job_id: 123, page: 1, per_page: 20)    # Grab the first 20.
+
+# Process items:
+resp.results.items.each do |item| ...
+```
+
+See also: [method](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Client.html#jobs_results-instance_method), [Item](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Response/JobsResults/Item.html), [REST](https://developers.neverbounce.com/v4.0/reference#jobs-results).
+
+### Download bulk job result as CSV
+
+```ruby
+resp = client.jobs_download(job_id: 123)
+
+# Parse:
+emails = CSV.parse(resp.raw)
+```
+
+See also: [method](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Client.html#jobs_download-instance_method), [REST](https://developers.neverbounce.com/v4.0/reference#jobs-download).
+
+### List/search bulk jobs
+
+```ruby
+resp = client.jobs_search
+resp = client.jobs_search(page: 1, per_page: 20)    # Grab the first 20.
+
+# Process items:
+resp.results.each do |item|
+```
+
+See also: [method](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Client.html#jobs_search-instance_method), [Result](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Response/JobsSearch/Result.html), [REST](https://developers.neverbounce.com/v4.0/reference#jobs-search).
+
+### Start an existing bulk job
+
+```ruby
+resp = client.jobs_start(job_id: 123)
+```
+
+See also: [method](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Client.html#jobs_start-instance_method), [REST](https://developers.neverbounce.com/v4.0/reference#jobs-start).
+
+### Parse an existing bulk job
+
+```ruby
+resp = client.jobs_parse(job_id: 123)
+```
+
+See also: [method](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Client.html#jobs_parse-instance_method), [REST](https://developers.neverbounce.com/v4.0/reference#jobs-parse).
+
+### Delete a bulk job
+
+```ruby
+resp = client.jobs_delete(job_id: 123)
+```
+
+See also: [method](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Client.html#jobs_delete-instance_method), [REST](https://developers.neverbounce.com/v4.0/reference#jobs-delete).
+
+## Debugging in the console
+
+When you make requests from the console, you'll notice that the responses don't show you any content, i.e. instance variables:
+
+```
+irb> resp = client.account_info
+=> #<NeverBounce::API::Response::AccountInfo:0x0056245c3e56f8>
+irb> resp.inspect
+=> "#<NeverBounce::API::Response::AccountInfo:0x0056245c3e56f8>"
+```
+
+It happens because by design our response containers **lazy-load their attributes** upon first access. Let's request an attribute:
+
+```
+irb> resp.status
+=> "success"
+irb> resp
+=> #<NeverBounce::API::Response::AccountInfo:0x0056245c3e56f8 @status="success">
+```
+
+In order to load **all** attributes use method `.touch`, like this:
+
+```
+irb> resp.touch
+=> #<NeverBounce::API::Response::AccountInfo:0x0056245c3e56f8 @status="success",
+@execution_time=98, @credits_info=#<NeverBounce::API::Response::CreditsInfo::Paid:0x0056245c430478
+@paid_credits_used=0, @free_credits_used=0, @paid_credits_remaining=1000000,
+@free_credits_remaining=973>,@job_counts=#<NeverBounce::API::Response::AccountInfo::JobCounts:0x0056245c430310
+@completed=10, @processing=0, @queued=0, @under_review=0>>
+```
+
+This is true for all API response containers and sub-containers. See [#touch](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Feature/Oattrs/InstanceMethods.html#touch-instance_method) in the docs.
+
+## Advanced usage
+
+For most regular tasks `Client` is powerful enough. However, if you need more control, you can use [Request](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Request.html), [Session](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Session.html) and [Response](http://rubydoc.info/github/NeverBounce/NeverBounceApi-Ruby/NeverBounce/API/Response/SuccessMessage.html) classes directly. Please refer to the online docs.
+
+For example, our [CLI gem](https://github.com/NeverBounce/NeverBounceCli-Ruby) uses them.
+
+## Command line interface
+
+We've got a gem called [neverbounce-cli](https://github.com/NeverBounce/NeverBounceCli-Ruby) which gives you a set of powerful CLI scripts to use our API.
+
+We recommend to install the CLI to have these tools at hand.
+
+## Compatibility
+
+Minimum Ruby version is 2.0.
+
+## Copyright
+
+NeverBounce API for Ruby is free and is licensed under the MIT License.
+Copyright &copy; 2017 NeverBounce.

data/lib/never_bounce/api/client.rb

@@ -0,0 +1,259 @@
+
+require "never_bounce/api/error"
+require "never_bounce/api/feature/basic_initialize"
+require "never_bounce/api/feature/require_attr"
+
+module NeverBounce; module API
+  # API client.
+  #
+  #   client = NeverBounce::API::Client.new(api_key: "api_key")
+  #
+  #   response = client.account_info
+  #   # => #<NeverBounce::API::Response::AccountInfo> or
+  #   # => #<NeverBounce::API::ErrorMessage>
+  #
+  #   response = client.single_check(credits_info: true, email: "support@neverbounce.com", timeout: 3)
+  #   # => #<NeverBounce::API::Response::JobsDownload> or
+  #   # => #<NeverBounce::API::ErrorMessage>
+  #
+  #   response = client.jobs_search(page: 1, per_page: 10)
+  #   # => #<NeverBounce::API::Response::JobsSearch> or
+  #   # => #<NeverBounce::API::ErrorMessage>
+  #
+  #   # ...
+  #
+  # @see #account_info
+  # @see #jobs_create
+  # @see #jobs_delete
+  # @see #jobs_download
+  # @see #jobs_parse
+  # @see #jobs_results
+  # @see #jobs_search
+  # @see #jobs_start
+  # @see #jobs_status
+  # @see #single_check
+  # @see https://developers.neverbounce.com/v4.0/reference
+  class Client
+    Feature::BasicInitialize.load(self)
+    Feature::RequireAttr.load(self)
+
+    attr_writer :api_key
+
+    # API key.
+    # @return [String]
+    def api_key
+      @api_key or raise AttributeError, "Attribute must be set: api_key"
+    end
+
+    #--------------------------------------- Misc
+
+    # Wrap request in a session, return response.
+    # @param request [Object] An instance of {Request::Base} successor.
+    # @return [Object] Result of {Session#response}.
+    def response_to(request)
+      Session.new(request: request).response
+    end
+    private :response_to
+
+    #--------------------------------------- Requests
+
+    # Make an <tt>account/info</tt> request.
+    # @return [Response::AccountInfo]
+    # @return [Response::ErrorMessage]
+    # @raise [API::Error]
+    # @raise [StandardError]
+    # @see Request::AccountInfo
+    # @see https://developers.neverbounce.com/v4.0/reference#account-info
+    def account_info
+      response_to(Request::AccountInfo.new({
+        api_key: api_key,
+      }))
+    end
+
+    # Make a <tt>jobs/create</tt> request.
+    # @param auto_parse [Boolean]
+    # @param auto_start [Boolean]
+    # @param filename [Boolean] Default is <tt>"YYYYMMDD-HHMMSS.csv"</tt> based on current time.
+    # @param remote_input [String] E.g. <tt>"http://isp.com/emails.csv"</tt>.
+    # @param run_sample [Boolean]
+    # @param supplied_input [Array<Array<email, name>>] E.g. <tt>[["alice@isp.com", "Alice Roberts"], ["bob.smith@gmail.com", "Bob Smith"]]</tt>.
+    # @return [Response::JobsCreate]
+    # @return [Response::ErrorMessage]
+    # @raise [API::Error]
+    # @raise [StandardError]
+    # @see Request::JobsCreate
+    # @see https://developers.neverbounce.com/v4.0/reference#jobs-create
+    def jobs_create(auto_parse: nil, auto_start: nil, filename: nil, remote_input: nil, run_sample: nil, supplied_input: nil)
+      raise ArgumentError, "`remote_input` and `supplied_input` can't both be given" if remote_input && supplied_input
+
+      input_location = if (v = remote_input)
+        # NOTE: Logical order: type, then value.
+        input = v
+        "remote_url"
+      elsif (v = supplied_input)
+        input = v
+        "supplied"
+      else
+        # NOTE: Not exactly sure what to raise here. From procedure standpoint missing argument is an `ArgumentError`.
+        raise ArgumentError, "Input not given, use `remote_input` or `supplied_input`"
+      end
+
+      filename ||= Time.now.strftime("%Y%m%d-%H%M%S.csv")
+
+      response_to(API::Request::JobsCreate.new({
+        api_key: api_key,
+        auto_parse: auto_parse,
+        auto_start: auto_start,
+        filename: filename,
+        input: input,
+        input_location: input_location,
+        run_sample: run_sample,
+      }))
+    end
+
+    # Make a <tt>jobs/delete</tt> request.
+    # @param job_id [Integer]
+    # @return [Response::JobsDelete]
+    # @return [Response::ErrorMessage]
+    # @raise [API::Error]
+    # @raise [StandardError]
+    # @see Request::JobsDelete
+    # @see https://developers.neverbounce.com/v4.0/reference#jobs-delete
+    def jobs_delete(job_id: nil)
+      response_to(Request::JobsDelete.new({
+        api_key: api_key,
+        job_id: job_id,
+      }))
+    end
+
+    # Make a <tt>jobs/download</tt> request.
+    # @param job_id [Integer]
+    # @return [Response::JobsDownload]
+    # @return [Response::ErrorMessage]
+    # @raise [API::Error]
+    # @raise [StandardError]
+    # @see Request::JobsDownload
+    # @see https://developers.neverbounce.com/v4.0/reference#jobs-download
+    def jobs_download(job_id: nil)
+      response_to(Request::JobsDownload.new({
+        api_key: api_key,
+        job_id: job_id,
+      }))
+    end
+
+    # Make a <tt>jobs/parse</tt> request.
+    # @param auto_start [Boolean]
+    # @param job_id [Integer]
+    # @return [Response::JobsParse]
+    # @return [Response::ErrorMessage]
+    # @raise [API::Error]
+    # @raise [StandardError]
+    # @see Request::JobsParse
+    # @see https://developers.neverbounce.com/v4.0/reference#jobs-parse
+    def jobs_parse(auto_start: nil, job_id: nil)
+      response_to(Request::JobsParse.new({
+        api_key: api_key,
+        auto_start: auto_start,
+        job_id: job_id,
+      }))
+    end
+
+    # Make a <tt>jobs/results</tt> request.
+    # @param job_id [Integer]
+    # @param page [Integer]
+    # @param per_page [Integer]
+    # @return [Response::JobsResults]
+    # @return [Response::ErrorMessage]
+    # @raise [API::Error]
+    # @raise [StandardError]
+    # @see Request::JobsResults
+    # @see https://developers.neverbounce.com/v4.0/reference#jobs-results
+    def jobs_results(job_id: nil, page: 1, per_page: nil)
+      response_to(Request::JobsResults.new({
+        api_key: api_key,
+        job_id: job_id,
+        page: page,
+        per_page: per_page,
+      }))
+    end
+
+    # Make a <tt>jobs/search</tt> request.
+    # @param job_id [Integer]
+    # @param page [Integer]
+    # @param per_page [Integer]
+    # @return [Response::JobsSearch]
+    # @return [Response::ErrorMessage]
+    # @raise [API::Error]
+    # @raise [StandardError]
+    # @see Request::JobsSearch
+    # @see https://developers.neverbounce.com/v4.0/reference#jobs-search
+    def jobs_search(job_id: nil, page: 1, per_page: nil)
+      response_to(Request::JobsSearch.new({
+        api_key: api_key,
+        job_id: job_id,
+        page: page,
+        per_page: per_page,
+      }))
+    end
+
+    # Make a <tt>jobs/start</tt> request.
+    # @param job_id [Integer]
+    # @param run_sample [Boolean]
+    # @return [Response::JobsResults]
+    # @return [Response::ErrorMessage]
+    # @raise [API::Error]
+    # @raise [StandardError]
+    # @see Request::JobsResults
+    # @see https://developers.neverbounce.com/v4.0/reference#jobs-start
+    def jobs_start(job_id: nil, run_sample: nil)
+      response_to(Request::JobsStart.new({
+        api_key: api_key,
+        job_id: job_id,
+        run_sample: run_sample,
+      }))
+    end
+
+    # Make a <tt>jobs/status</tt> request.
+    # @param job_id [Integer]
+    # @return [Response::JobsStatus]
+    # @return [Response::ErrorMessage]
+    # @raise [API::Error]
+    # @raise [StandardError]
+    # @see Request::JobsStatus
+    # @see https://developers.neverbounce.com/v4.0/reference#jobs-status
+    def jobs_status(job_id: nil)
+      response_to(Request::JobsStatus.new({
+        api_key: api_key,
+        job_id: job_id,
+      }))
+    end
+
+    # Make a <tt>single/check</tt> request.
+    # @param address_info [Boolean]
+    # @param credits_info [Boolean]
+    # @param email [String]
+    # @param timeout [Integer]
+    # @return [Response::SingleCheck]
+    # @return [Response::ErrorMessage]
+    # @raise [API::Error]
+    # @raise [StandardError]
+    # @see Request::SingleCheck
+    # @see https://developers.neverbounce.com/v4.0/reference#single-check
+    def single_check(address_info: nil, credits_info: nil, email: nil, timeout: nil)
+      response_to(Request::SingleCheck.new({
+        address_info: address_info,
+        api_key: api_key,
+        credits_info: credits_info,
+        email: email,
+        timeout: timeout,
+      }))
+    end
+  end
+end; end
+
+#
+# Implementation notes:
+#
+# * `api_key` is so common that we validate its presence in reader method rather than elsewhere.
+#   Hence there isn't a `require_attr(:api_key)` anywhere.
+#   `api_key` is Client's own business, hence the presence validation at this level.