emailverify 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81ab97eed6690176d532cd155fe2d5952ab4cf47887b8c0a16d0ff0605faf9c1
+  data.tar.gz: ed2cd57e4596d1977b90941c259aa4e9444171ddb2978c4dfb144266201d1e1b
+SHA512:
+  metadata.gz: 9ae75962bb1ce322a1776bf17a59f6d56dc9fdc97ffe20c81c49dd43807ec9facf07a7712e75396ade2584653504ef4e79a0fbe3ad8f3d2865e75b973da64eea
+  data.tar.gz: dd366392f16f460abc192d1c02c9598005b85b92fcb0ad9923e7788b3b820736b4fa78ecc6bced3dcd5c1abdae502b2c62ffea00c8865a539fbb00dcda15eb2e

data/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+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 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,81 @@
+# Emailverify Ruby Gem
+
+emailverify is a small, object-oriented Ruby client for the EmailVerify.io API.
+
+Features
+- Simple configuration (only the API key is required by default)
+- Clean wrapper methods: validate, valid?, and check_balance
+- Abstracts HTTP details using Faraday
+
+Quick start
+
+1) Add to your Gemfile or install locally
+
+```ruby
+gem "emailverify", git: "https://github.com/Clustox/emailverify-ruby.git"
+```
+
+
+2) Configure (only api_key is strictly required)
+
+```ruby
+Emailverify.configure do |config|
+  config.api_key = "YOUR_API_KEY"
+end
+
+request = Emailverify::Request.new
+result = request.validate("jane@example.com")
+
+if request.valid?("jane@example.com")
+  puts "valid"
+else
+  puts "invalid"
+end
+
+balance = request.check_balance # or client.check_balance(batch_id)
+
+# Validate example (EmailVerify.io v1)
+# The gem will call:
+# https://app.emailverify.io/api/v1/validate?key=<YOUR_API_KEY>&email=valid@example.com
+# and return parsed JSON, for example:
+# {
+#   "email": "jhon123@gmail.com",
+#   "status": "valid",
+#   "sub_status": "permitted"
+# }
+
+# Modern usage (Response objects)
+# The client now returns an `Emailverify::Response` wrapper with helper accessors.
+Emailverify.configure do |c|
+  c.apikey = ENV['EMAILVERIFY_API_KEY']
+end
+
+# Module-level convenience
+resp = Emailverify.validate(email: 'jane@example.com')
+puts resp.status            # => 'valid' (string)
+puts resp.sub_status        # => 'permitted' or nil
+puts resp.to_h              # => raw Hash if you need it
+
+balance = Emailverify.check_balance
+puts balance.api_status     # => 'enabled'
+puts balance.available_credits
+
+# Balance example (EmailVerify.io v2)
+# The gem will call:
+# https://app.emailverify.io/api/v2/check-account-balance?key=<YOUR_API_KEY>
+# and return the parsed JSON, for example:
+# {
+#   "api_status": "enabled",
+#   "available_credits": 16750
+# }
+
+```
+
+Notes on endpoints
+The gem ships with sensible defaults for endpoints, but your service may have different paths. You can pass an `endpoint:` option to each method or override the configured endpoints via `Emailverify.configure`.
+
+Security
+- The client will send the API key in an Authorization header for endpoints that expect it. The EmailVerify.io endpoints used by this gem (v1 validate and v2 check-account-balance) use the `key` query parameter, and the client passes this automatically for those methods.
+
+Contributing
+Pull requests welcome. Run tests with `bundle install && bundle exec rake`.

data/Rakefile

@@ -0,0 +1,11 @@
+require "rake/testtask"
+require "rspec/core/rake_task"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = Dir["spec/**/*_spec.rb"]
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/emailverify.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name          = "emailverify"
+  spec.version       = Emailverify::VERSION rescue "0.1.0"
+  spec.authors       = ["Salman Aslam"]
+  spec.email         = ["you@example.com"]
+
+  spec.summary       = "Ruby wrapper for the EmailVerify.io API"
+  spec.description   = "A small, object-oriented Ruby client for the EmailVerify.io service."
+  spec.homepage      = "https://github.com/yourname/emailverify"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = '>= 2.7.0'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").select { |f| f =~ /^(lib|README|LICENSE|Rakefile|emailverify\.gemspec)/ }
+  rescue
+    Dir["lib/**/*"] + %w[README.md LICENSE Rakefile emailverify.gemspec]
+  end
+
+  # 👉 Fix open-ended dependency warnings
+  spec.add_runtime_dependency "faraday", "~> 1.0"
+  spec.add_runtime_dependency "json", "~> 2.0"
+
+  # 👉 Dev dependency also fixed
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/emailverify/configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Emailverify
+  class Configuration
+    attr_accessor :api_key, :timeout, :logger, :endpoints
+    attr_reader :base_url
+
+    def initialize
+      @api_key = nil
+      # Base URL is fixed to the official EmailVerify.io host
+      @base_url = "https://app.emailverify.io"
+      @timeout = 10
+      @logger = nil
+      # endpoints can be overridden by the user to match their API paths
+      @endpoints = {
+        # EmailVerify.io single email validation endpoint (v1)
+        validate: "/api/v1/validate",
+        # EmailVerify.io check account balance endpoint (v2)
+        check_balance: "/api/v2/check-account-balance"
+      }
+    end
+
+    # ZeroBounce-style alias: allow `config.apikey = 'key'` to set api_key
+    def apikey=(val)
+      self.api_key = val
+    end
+
+    def apikey
+      api_key
+    end
+  end
+end

data/lib/emailverify/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Emailverify
+  class Error < StandardError; end
+  class AuthenticationError < Error; end
+  class RequestError < Error; end
+  class UnexpectedResponseError < Error; end
+end

data/lib/emailverify/request.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Emailverify
+  class Request
+    DEFAULT_HEADERS = { "Content-Type" => "application/json" }.freeze
+
+    def initialize(api_key: nil, base_url: nil, timeout: nil)
+      @config = Emailverify.configuration
+      @api_key = api_key || @config.api_key
+      @base_url = base_url || @config.base_url
+      @timeout = timeout || @config.timeout
+
+      raise AuthenticationError, "API key missing" unless @api_key
+      raise RequestError, "base_url must be configured" unless @base_url
+
+      @conn = Faraday.new(url: @base_url) do |faraday|
+        faraday.request :url_encoded
+        faraday.adapter Faraday.default_adapter
+        faraday.options.timeout = @timeout
+      end
+    end
+
+    # Validate a single email address. Returns parsed JSON from the API.
+    # By default this uses EmailVerify.io's v1 endpoint which expects GET
+    # with query params `key` and `email`, e.g.:
+    # https://app.emailverify.io/api/v1/validate?key=yourapikey&email=valid@example.com
+    # You can override the endpoint path via `endpoint:` if the API differs.
+    def validate(email, endpoint: nil)
+      path = endpoint || @config.endpoints[:validate]
+      params = { key: @api_key, email: email }
+      request(:get, path, params: params)
+    end
+
+    # Return boolean true/false for whether the email is valid.
+    # For EmailVerify.io v1 the API returns `status` with values like
+    # "valid", "invalid" and may include `sub_status` such as "permitted".
+    # This method returns true when `status` equals "valid" (case-insensitive).
+    def valid?(email, endpoint: nil)
+      resp = validate(email, endpoint: endpoint)
+
+      # Support Response objects or raw Hashes
+      status_value = if resp.respond_to?(:status)
+        resp.status
+      elsif resp.is_a?(Hash)
+        resp["status"] || resp[:status]
+      else
+        nil
+      end
+
+      return false unless status_value
+      status_value.to_s.strip.downcase == "valid"
+    end
+
+    # Check balance or status of a completed batch. Accepts an id or options.
+    # Check account balance. By default this calls the EmailVerify.io endpoint
+    # /api/v2/check-account-balance and passes the API key as the `key` query param
+    # (https://app.emailverify.io/api/v2/check-account-balance?key=<Your_API_Key>)
+    # If your provider uses a different pattern you may pass `endpoint:` or
+    # override `Emailverify.configuration.endpoints[:check_balance]`.
+    def check_balance(batch_id = nil, endpoint: nil)
+      path = endpoint || @config.endpoints[:check_balance]
+
+      # If a batch_id is provided, append it to the path (useful for batch status
+      # endpoints that accept an id as part of the path).
+      if batch_id
+        path = File.join(path, batch_id.to_s)
+      end
+
+      # EmailVerify.io expects the API key as query param `key` for this endpoint.
+      params = { key: @api_key }
+
+      request(:get, path, params: params)
+    end
+
+    # (auth_check endpoint removed) If you need a custom check you can call
+    # `client.request(:get, path, params: { key: ... })` directly or supply the
+    # endpoint to the high-level methods.
+
+    private
+
+    def request(method, path, json: nil, params: nil)
+      raise RequestError, "path is required" unless path
+
+      headers = DEFAULT_HEADERS.merge("Authorization" => "Bearer #{@api_key}")
+
+      response = @conn.send(method) do |req|
+        req.url path
+        req.headers.update(headers)
+        req.params.update(params) if params
+        req.body = JSON.generate(json) if json
+      end
+
+      case response.status
+      when 200..299
+        parsed = parse_body(response.body)
+        # Wrap parsed JSON hashes in a Response object for a nicer API
+        return Emailverify::Response.new(parsed) if parsed.is_a?(Hash)
+        parsed
+      when 401, 403
+        raise AuthenticationError, "authentication failed (status=#{response.status})"
+      else
+        raise RequestError, "request failed (status=#{response.status}): #{response.body}"
+      end
+    rescue Faraday::TimeoutError => e
+      raise RequestError, "request timeout: #{e.message}"
+    rescue Faraday::ConnectionFailed => e
+      raise RequestError, "connection failed: #{e.message}"
+    end
+
+    def parse_body(body)
+      return {} if body.nil? || body.strip.empty?
+      JSON.parse(body)
+    rescue JSON::ParserError
+      raise UnexpectedResponseError, "Invalid JSON response"
+    end
+
+    def truthy_value?(val)
+      return true if val == true
+      return true if val.is_a?(String) && val.strip.downcase == "true"
+      return true if val.is_a?(Numeric) && val.to_f > 0
+      false
+    end
+
+    def falsy_value?(val)
+      return true if val == false
+      return true if val.nil?
+      return true if val.is_a?(String) && val.strip.empty?
+      return true if val.is_a?(Numeric) && val.to_f == 0
+      false
+    end
+  end
+end

data/lib/emailverify/response.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Emailverify
+  # Generic Response wrapper for Emailverify API responses.
+  #
+  # Provides a V1Response module with common helpers similar to
+  # the ZeroBounce response structure (status, sub_status, disposable?, ...).
+  # Use by wrapping a parsed JSON Hash:
+  #
+  # resp = Emailverify::Response.new(parsed_json)
+  # resp.status
+  class Response
+    attr_reader :body
+
+    def initialize(body)
+      # normalize keys to strings for convenient access
+      @body = (body || {}).each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+    end
+
+    # Return underlying hash
+    def to_h
+      @body.dup
+    end
+
+    # Minimal EmailVerify-specific helpers. This gem's API response shape
+    # differs from ZeroBounce; expose small, explicit accessors instead of
+    # mirroring ZeroBounce internals.
+
+    # Email address returned by the API (if present)
+    def email
+      @email ||= @body["email"] || @body["email_address"]
+    end
+
+    # Status field as returned by the API (string)
+    def status
+      @status ||= @body["status"]
+    end
+
+    # Sub-status (string) if present
+    def sub_status
+      @sub_status ||= @body["sub_status"] || @body["sub-status"] || @body["substatus"]
+    end
+
+    # For balance responses: api_status
+    def api_status
+      @api_status ||= @body["api_status"]
+    end
+
+    # For balance responses: available_credits as Integer
+    def available_credits
+      val = @body["available_credits"] || @body["availableCredits"] || @body["credits"]
+      val.nil? ? nil : val.to_i
+    end
+
+    # Generic accessor by key
+    def [](key)
+      @body[key.to_s]
+    end
+  end
+end

data/lib/emailverify/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Emailverify
+  VERSION = "0.1.0"
+end

data/lib/emailverify.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "emailverify/version"
+require_relative "emailverify/configuration"
+require_relative "emailverify/errors"
+require_relative "emailverify/request"
+require_relative "emailverify/response"
+
+module Emailverify
+  class << self
+    # Configure the gem using a block:
+    #
+    # Emailverify.configure do |config|
+    #   config.apikey = "xxx"
+    # end
+    def configure
+      yield configuration if block_given?
+      configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset!
+      @configuration = Configuration.new
+    end
+
+    # Convenience client helper — builds a client using current configuration
+    def request
+      @request ||= Request.new(api_key: configuration.api_key, base_url: configuration.base_url, timeout: configuration.timeout)
+    end
+
+    def validate(email:, endpoint: nil)
+      request.validate(email, endpoint: endpoint)
+    end
+
+    def valid?(email:, endpoint: nil)
+      request.valid?(email, endpoint: endpoint)
+    end
+
+    def check_balance(batch_id = nil, endpoint: nil)
+      request.check_balance(batch_id, endpoint: endpoint)
+    end
+
+    # Load configuration from environment variables; helpful for CLI/CI use.
+    # EMAILVERIFY_API_KEY and EMAILVERIFY_BASE_URL are supported, but base_url
+    # will be ignored and remain the fixed app.emailverify.io host per design.
+    def configure_from_env(env = ENV)
+      configuration.api_key ||= env["EMAILVERIFY_API_KEY"]
+      # ignore env base_url to keep fixed host; but store if present
+      configuration
+    end
+  end
+end
+

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: emailverify
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Salman Aslam
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-11-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A small, object-oriented Ruby client for the EmailVerify.io service.
+email:
+- you@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- emailverify.gemspec
+- lib/emailverify.rb
+- lib/emailverify/configuration.rb
+- lib/emailverify/errors.rb
+- lib/emailverify/request.rb
+- lib/emailverify/response.rb
+- lib/emailverify/version.rb
+homepage: https://github.com/yourname/emailverify
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Ruby wrapper for the EmailVerify.io API
+test_files: []