First commit of quickemailverification-ruby package

README.md

@@ -0,0 +1,102 @@
+<p align="center">
+  <img src="https://quickemailverification.com/extra/images/logo_github.png" alt="Quick Email Verification">
+  <br>
+</p>
+
+
+# Official Email Validation API library client for Ruby
+
+QuickEmailVerification provides the quickest way to avoid fake / invalid emails.
+
+* Get actual users by scanning email address.
+* Remove invalid, dead and fake emails from your email list.
+* Save time and money by sending mail to actual users.
+
+## Let's Get Started
+
+To begin, signUp at [quickemailverification.com](https://quickemailverification.com) and create a FREE account. After signup logged in, click on **[API Settings](https://quickemailverification.com/apisettings)** and then click **Add API Key**. To use API you need 2 parameters.
+
+email - (string) This is a email address you need to verify. It should be url encoded.
+
+apikey - (string) This is the key you generated from "api settings" page.
+
+NOTE: Keep API key with you. You'll need it to setup the client as explained below.
+
+## Installation
+
+Make sure you have [rubygems](https://rubygems.org) installed
+
+```bash
+$ gem install quickemailverification
+```
+
+#### Versions
+
+Works with [ 1.8.6 / 1.8.7 / 1.9.1 / 1.9.2 / 1.9.3 / 2.0.0 / 2.1.0 / 2.1.1 ]
+
+## Usage
+
+```ruby
+require "quickemailverification"
+
+client   = QuickEmailVerification::Client.new('Your_API_Key_Here')
+quickemailverification  = client.quickemailverification()
+response = quickemailverification.verify("[email protected]")
+puts response.body
+```
+
+### Response information
+
+A successful API call responds with the following values:
+
+- **result** `string` - The verified results will be: `valid`, `invalid`, `unknown`
+- **reason** `string` - Reason definitions are as below:
+  - `invalid_email` - Specified email has invalid email address syntax
+  - `invalid_domain` - Domain name does not exist
+  - `rejected_email` - SMTP server rejected email. Email does not exist
+  - `accepted_email` - SMTP server accepted email address
+  - `no_connect` - SMTP server connection failure
+  - `timeout` -  Session time out occurred at SMTP server
+  - `unavailable_smtp` - SMTP server is not available to process request
+  - `unexpected_error` - An unexpected error has occurred
+  - `no_mx_record` - Could not get MX records for domain
+  - `temporarily_blocked` - Email is temporarily greylisted 
+  - `exceeded_storage` - SMTP server rejected email. Exceeded storage allocation
+
+- **disposable**  `true | false` - *true* if the email address uses a *disposable* domain
+- **accept_all**  `true | false` - *true* if the domain appears to *accept all* emails delivered to that domain
+- **role**  `true | false` - *true* if the email address is a *role* address (`[email protected]`, `[email protected]`, etc)
+- **free** `true | false` - *true* if the email address is from free email provider like Gmail, Yahoo!, Hotmail etc.
+- **email** `string` - Returns a normalized version. (`[email protected]` -> `[email protected]`)
+- **user** `string` - The local part of an email address. (`[email protected]` -> `niki`)
+- **domain** `string` - The domain of the provided email address. (`[email protected]` -> `example.com`)
+- **safe_to_send** `true | false` - *true* if the email address is safe for deliverability
+- **did_you_mean** `string` - Returns email suggestions if specific typo errors found in email
+- **success** `true | false` - *true* if the API request was successful
+- **message** `string` - Describes API call failure reason
+
+### HTTP Response headers
+
+Total remaining credits can be found by http response header. It contains overall remaining credits, including Persistent & Per day credits.
+
+- **X-QEV-Remaining-Credits** - Your remaining email verification credits (i.e. Per Day Credits + Persistent Credits).
+
+## HTTP status codes for QuickEmailVerification API calls
+
+QuickEmailVerification API also returns following HTTP status codes to indicate success or failure of request.
+
+- `200` - Request is completed successfully.
+- `400` - Server can not understand the request sent to it. This is kind of response can occur if parameters are passed wrongly.
+- `401` - Server can not verify your authentication to use api. Please check whether API key is proper or not.
+- `402` - You are running out of your credit limit.
+- `404` - Requested API can not be found on server.
+- `429` - Too many requests. Rate limit exceeded.
+
+## License
+MIT
+
+## Bug Reports
+Report [here](https://github.com/quickemailverification/quickemailverification-ruby/issues).
+
+## Need Help? Feel free to contact us
+https://quickemailverification.com/contact-us

lib/.directory

@@ -0,0 +1,4 @@
+[Dolphin]
+Timestamp=2018,1,2,10,35,26
+Version=3
+ViewMode=2

lib/quickemailverification.rb

@@ -0,0 +1,8 @@
+require "rubygems"
+
+require "quickemailverification/client"
+require "quickemailverification/error"
+require "quickemailverification/http_client"
+
+module QuickEmailVerification
+end

lib/quickemailverification/api/quickemailverification.rb

@@ -0,0 +1,29 @@
+module QuickEmailVerification
+
+  module Api
+
+    # QuickEmailVerification Class for email verification
+    class Quickemailverification
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Verify email address and get detailed response
+      #
+      # '/verify?email=:email' GET
+      #
+      # email - send email address in query parameter
+      def verify(email, options = {})
+        body = options.fetch("query", {})
+
+        email = CGI::escape(email)
+
+        @client.get("/verify?email=#{email}", body, options)
+      end
+
+    end
+
+  end
+
+end

lib/quickemailverification/client.rb

@@ -0,0 +1,21 @@
+require "faraday"
+require "json"
+
+require "quickemailverification/api/quickemailverification"
+
+module QuickEmailVerification
+
+  class Client
+
+    def initialize(auth = {}, options = {})
+      @http_client = QuickEmailVerification::HttpClient::HttpClient.new(auth, options)
+    end
+
+    # QuickEmailVerification Class for email verification
+    def quickemailverification()
+      QuickEmailVerification::Api::Quickemailverification.new(@http_client)
+    end
+
+  end
+
+end

lib/quickemailverification/error.rb

@@ -0,0 +1,9 @@
+require "quickemailverification/error/client_error"
+
+module QuickEmailVerification
+
+  module Error
+
+  end
+
+end

lib/quickemailverification/error/client_error.rb

@@ -0,0 +1,18 @@
+module QuickEmailVerification
+
+  module Error
+
+    class ClientError < ::StandardError
+
+      attr_reader :code
+
+      def initialize(message, code)
+        @code = code
+        super message
+      end
+
+    end
+
+  end
+
+end

lib/quickemailverification/http_client.rb

@@ -0,0 +1,124 @@
+require "quickemailverification/http_client/auth_handler"
+require "quickemailverification/http_client/error_handler"
+require "quickemailverification/http_client/request_handler"
+require "quickemailverification/http_client/response"
+require "quickemailverification/http_client/response_handler"
+
+module QuickEmailVerification
+
+  module HttpClient
+
+    # Main HttpClient which is used by Api classes
+    class HttpClient
+
+      attr_accessor :options, :headers
+
+      def initialize(auth = {}, options = {})
+
+        if auth.is_a?(String)
+          auth = { :http_header => auth }
+        end
+
+        @options = {
+          :base => "http://api.quickemailverification.com",
+          :api_version => "v1",
+          :user_agent => "quickemailverification-ruby/1.0.1 (https://github.com/quickemailverification/quickemailverification-ruby)"
+        }
+
+        @options.update(options)
+
+        @headers = {
+          "user-agent" => @options[:user_agent]
+        }
+
+        if @options.has_key?(:headers)
+          @headers.update(Hash[@options[:headers].map { |k, v| [k.downcase, v] }])
+          @options.delete(:headers)
+        end
+
+        @client = Faraday.new(@options[:base]) do |conn|
+          conn.use(QuickEmailVerification::HttpClient::AuthHandler, auth)
+          conn.use(QuickEmailVerification::HttpClient::ErrorHandler)
+
+          conn.adapter(Faraday.default_adapter)
+        end
+      end
+
+      def get(path, params = {}, options = {})
+        request(path, nil, "get", options.merge({ :query => params }))
+      end
+
+      def post(path, body = {}, options = {})
+        request(path, body, "post", options)
+      end
+
+      def patch(path, body = {}, options = {})
+        request(path, body, "patch", options)
+      end
+
+      def delete(path, body = {}, options = {})
+        request(path, body, "delete", options)
+      end
+
+      def put(path, body = {}, options = {})
+        request(path, body, "put", options)
+      end
+
+      # Intermediate function which does three main things
+      #
+      # - Transforms the body of request into correct format
+      # - Creates the requests with give parameters
+      # - Returns response body after parsing it into correct format
+      def request(path, body, method, options)
+        options = @options.merge(options)
+
+        options[:headers] = options[:headers] || {}
+        options[:headers] = @headers.merge(Hash[options[:headers].map { |k, v| [k.downcase, v] }])
+
+        options[:body] = body
+
+        if method != "get"
+          options[:body] = options[:body] || {}
+          options = set_body(options)
+        end
+
+        response = create_request(method, path, options)
+
+        env = response.env
+        body = get_body(env)
+
+        QuickEmailVerification::HttpClient::Response.new(body, env.status, env.response_headers)
+      end
+
+      # Creating a request with the given arguments
+      #
+      # If api_version is set, appends it immediately after host
+      def create_request(method, path, options)
+        version = options.has_key?(:api_version) ? "/#{options[:api_version]}" : ""
+
+        path = "#{version}#{path}"
+
+        instance_eval <<-RUBY, __FILE__, __LINE__ + 1
+          @client.#{method}(path) do |req|
+            req.body = options[:body]
+            req.headers.update(options[:headers])
+            req.params.update(options[:query]) if options[:query]
+          end
+        RUBY
+      end
+
+      # Get response body in correct format
+      def get_body(env)
+        QuickEmailVerification::HttpClient::ResponseHandler.get_body(env)
+      end
+
+      # Set request body in correct format
+      def set_body(options)
+        QuickEmailVerification::HttpClient::RequestHandler.set_body(options)
+      end
+
+    end
+
+  end
+
+end

lib/quickemailverification/http_client/auth_handler.rb

@@ -0,0 +1,73 @@
+require "base64"
+
+module QuickEmailVerification
+
+  module HttpClient
+
+    # AuthHandler takes care of devising the auth type and using it
+    class AuthHandler < Faraday::Middleware
+
+      HTTP_HEADER = 1
+
+      def initialize(app, auth = {}, options = {})
+        @auth = auth
+        super(app)
+      end
+
+      def call(env)
+        if !@auth.empty?
+          auth = get_auth_type
+          flag = false
+
+          if auth == HTTP_HEADER
+            env = http_header(env)
+            flag = true
+          end
+
+          if !flag
+            raise StandardError.new "Unable to calculate authorization method. Please check"
+          end
+        else
+          raise StandardError.new "Server requires authentication to proceed further. Please check"
+        end
+
+        @app.call(env)
+      end
+
+      # Calculating the Authentication Type
+      def get_auth_type()
+
+        if @auth.has_key?(:http_header)
+          return HTTP_HEADER
+        end
+
+        return -1
+      end
+
+      # Authorization with HTTP header
+      def http_header(env)
+        env[:request_headers]["Authorization"] = "token #{@auth[:http_header]}"
+
+        return env
+      end
+
+      def query_params(url)
+        if url.query.nil? or url.query.empty?
+          {}
+        else
+          Faraday::Utils.parse_query(url.query)
+        end
+      end
+
+      def merge_query(env, query)
+        query = query.update query_params(env[:url])
+
+        env[:url].query = Faraday::Utils.build_query(query)
+
+        return env
+      end
+    end
+
+  end
+
+end