zerobounce-sdk 1.1.1 → 2.1.8

data/lib/zerobounce.rb

@@ -2,19 +2,23 @@
 # frozen_string_literal: true
 
 require 'date'
+require 'tempfile'
 
 require 'zerobounce/error'
 require 'zerobounce/version'
+require 'zerobounce/download_type'
+require 'zerobounce/get_file_options'
+require 'zerobounce/get_file_helper'
+require 'zerobounce/validate_status'
+require 'zerobounce/validate_sub_status'
 require 'zerobounce/request'
 require 'zerobounce/mock_request'
 require 'zerobounce/configuration'
+require 'zerobounce/api_urls'
 
 # Validate an email address with Zerobounce.net
 module Zerobounce
 
-  API_ROOT_URL      = 'https://api.zerobounce.net/v2'
-  BULK_API_ROOT_URL = 'https://bulkapi.zerobounce.net/v2'
-
   class << self
     attr_writer :configuration
 
@@ -28,6 +32,14 @@ module Zerobounce
     end
     alias config configuration
 
+    # Whether a getfile response body looks like a JSON error payload (including HTTP 200).
+    #
+    # @param [String] body
+    # @return [Boolean]
+    def get_file_json_indicates_error?(body)
+      GetFileHelper.json_indicates_error?(body)
+    end
+
     # Configure Zerobounce inside a block.
     #
     # @example
@@ -56,6 +68,7 @@ module Zerobounce
     #   "domain": null,
     #   "domain_age_days": "9692",
     #   "smtp_provider": "example",
+    #   "catchall_domain": false,
     #   "mx_found": "true",
     #   "mx_record": "mx.example.com",
     #   "firstname": "zero",
@@ -135,10 +148,13 @@ module Zerobounce
     #   "sub_status_mailbox_quota_exceeded": 0,
     #   "sub_status_forcible_disconnect": 0,
     #   "sub_status_failed_smtp_connection": 0,
+    #   "sub_status_accept_all": 0,
     #   "sub_status_mx_forward": 0,
     #   "sub_status_alternate": 0,
-    #   "sub_status_blocked": 0,
     #   "sub_status_allowed": 0,
+    #   "sub_status_blocked": 0,
+    #   "sub_status_gold": 0,
+    #   "sub_status_role_based_accept_all": 0,
     #   "start_date": "1/1/2018",
     #   "end_date": "12/12/2023"
     # }
@@ -184,6 +200,7 @@ module Zerobounce
     #     "domain": null,
     #     "domain_age_days": "9692",
     #     "smtp_provider": "example",
+    #     "catchall_domain": false,
     #     "mx_found": "true",
     #     "mx_record": "mx.example.com",
     #     "firstname": "zero",
@@ -215,7 +232,7 @@ module Zerobounce
         })
       end
       params = {email_batch: email_batch}
-      results = @@request.bulk_post('validatebatch', params)
+      results = @@request.post('validatebatch', params)
       return results['email_batch']
     end
 
@@ -243,7 +260,8 @@ module Zerobounce
         last_name_column: 3,
         gender_column: 4,
         has_header_row: true,
-        return_url: nil
+        return_url: nil,
+        allow_phase_2: nil
       )
       params = {
         email_address_column: email_address_column,
@@ -253,9 +271,34 @@ module Zerobounce
       params[:last_name_column] = last_name_column if last_name_column
       params[:gender_column] = gender_column if gender_column
       params[:return_url] = return_url if return_url
+      unless allow_phase_2.nil?
+        params[:allow_phase_2] = allow_phase_2 ? 'true' : 'false'
+      end
       @@request.bulk_post('sendfile', params, 'multipart/form-data', filepath)
     end
 
+    # Validate CSV from a stream (IO or String).
+    #
+    # @param [IO, String] io Stream or string content to upload
+    # @param [String] file_name Filename for the upload (e.g. "emails.csv")
+    # @option [Int] :email_address_column (same as validate_file_send)
+    # @option [Int] :first_name_column
+    # @option [Int] :last_name_column
+    # @option [Int] :gender_column
+    # @option [Int] :has_header_row
+    # @option [Int] :return_url
+    # @option [Boolean] :allow_phase_2 When set, sends allow_phase_2 (validation bulk only).
+    # @return [Hash] same as validate_file_send
+    def validate_file_send_stream(io, file_name, **opts)
+      content = io.respond_to?(:read) ? io.read : io.to_s
+      Tempfile.create(['zb', File.extname(file_name)]) do |tmp|
+        tmp.binmode
+        tmp.write(content)
+        tmp.rewind
+        validate_file_send(tmp.path, **opts)
+      end
+    end
+
     # Get validate file status
     #
     # @param [String] :file_id Id of the file.
@@ -279,13 +322,20 @@ module Zerobounce
 
     # Get validate results file
     #
-    # @param [String] :file_id Id of the file.
-    #
-    # @return [String/File?]
-    def validate_file_get(file_id)
-      # todo:
-      params = {file_id: file_id}
-      @@request.bulk_get('getfile', params)
+    # @param [String] file_id Id of the file.
+    # @param [Zerobounce::GetFileOptions, nil] options Optional +download_type+ and +activity_data+ (validation bulk only).
+    #
+    # @return [String] file body on success
+    # @raise [RuntimeError] on API/JSON error responses
+    def validate_file_get(file_id, options = nil)
+      params = { file_id: file_id }
+      if options
+        params[:download_type] = options.download_type if options.download_type
+        unless options.activity_data.nil?
+          params[:activity_data] = options.activity_data ? 'true' : 'false'
+        end
+      end
+      @@request.bulk_getfile('getfile', params)
     end
 
     # Delete validate file
@@ -333,15 +383,37 @@ module Zerobounce
       @@request.bulk_post('scoring/sendfile', params, 'multipart/form-data', filepath)
     end
 
-    # Get validate results file
+    # Score CSV from a stream (IO or String).
+    #
+    # @param [IO, String] io Stream or string content to upload
+    # @param [String] file_name Filename for the upload (e.g. "emails.csv")
+    # @option [Int] :email_address_column (same as scoring_file_send)
+    # @option [Int] :has_header_row
+    # @option [Int] :return_url
+    # @return [Hash] same as scoring_file_send
+    def scoring_file_send_stream(io, file_name, **opts)
+      content = io.respond_to?(:read) ? io.read : io.to_s
+      Tempfile.create(['zb', File.extname(file_name)]) do |tmp|
+        tmp.binmode
+        tmp.write(content)
+        tmp.rewind
+        scoring_file_send(tmp.path, **opts)
+      end
+    end
+
+    # Get scoring bulk results file
     #
-    # @param [String] :file_id Id of the file.
+    # @param [String] file_id Id of the file.
+    # @param [Zerobounce::GetFileOptions, nil] options Optional +download_type+; +activity_data+ is not sent.
     #
-    # @return [String/File?]
-    def scoring_file_get(file_id)
-      # todo:
-      params = {file_id: file_id}
-      @@request.bulk_get('scoring/getfile', params)
+    # @return [String] file body on success
+    # @raise [RuntimeError] on API/JSON error responses
+    def scoring_file_get(file_id, options = nil)
+      params = { file_id: file_id }
+      if options && options.download_type
+        params[:download_type] = options.download_type
+      end
+      @@request.bulk_getfile('scoring/getfile', params)
     end
 
     # Get validate file status
@@ -427,19 +499,120 @@ module Zerobounce
     #    ]
     # }
     def guessformat(domain, first_name: '', middle_name: '', last_name: '')
-      params = {
-        domain: domain
-      }
-      unless first_name.empty?
-        params['first_name'] = first_name
-      end
-      unless middle_name.empty?
-        params['middle_name'] = middle_name
+      warn "[DEPRECATION] `guessformat` is deprecated and will be removed in a future version.\n" \
+           "Please use `find_email` or `find_domain` instead."
+      params = {domain: domain}
+      params[:first_name] = first_name unless first_name.nil? || first_name.empty?
+      params[:middle_name] = middle_name unless middle_name.nil? || middle_name.empty?
+      params[:last_name] = last_name unless last_name.nil? || last_name.empty?  
+      @@request.get('guessformat', params)
+    end
+
+
+    # Find email address format
+    #
+    # @option [String] domain Domain to search within (e.g. example.com). Required if company_name is not provided.
+    # @option [String] company_name Company name to search within (e.g. Example). Required if domain is not provided.
+    # @option [String] first_name First name of target.
+    # @option [String] middle_name Middle name of target.
+    # @option [String] last_name Last name of target.
+    #
+    # @return [Hash]
+    # {
+    #   "email": "john@zerobounce.net",
+    #   "email_confidence": "medium",
+    #   "domain": "zerobounce.net",
+    #   "company_name": "ZeroBounce",
+    #   "did_you_mean": "",
+    #   "failure_reason": ""
+    # }
+    def find_email(first_name, domain: '', company_name: '', middle_name: '', last_name: '')
+      # Validate that exactly one of domain or company_name is provided
+      if (domain.nil? || domain.empty?) && (company_name.nil? || company_name.empty?)
+        raise ArgumentError, "Either domain or company_name must be provided"
+      elsif !(domain.nil? || domain.empty?) && !(company_name.nil? || company_name.empty?)
+        raise ArgumentError, "Only one of domain or company_name can be provided"
       end
-      unless last_name.empty?
-        params['last_name'] = last_name
+
+      params = { first_name: first_name }
+      params[:domain] = domain unless domain.nil? || domain.empty?
+      params[:company_name] = company_name unless company_name.nil? || company_name.empty?
+      params[:middle_name] = middle_name unless middle_name.nil? || middle_name.empty?
+      params[:last_name] = last_name unless last_name.nil? || last_name.empty?
+
+      @@request.get('guessformat', params)
+    end
+
+    # Find domain format
+    # 
+    # @option [String] domain Domain to search within (e.g. example.com). Required if company_name is not provided.
+    # @option [String] company_name Company name to search within (e.g. Example). Required if domain is not provided.
+    # 
+    # @return [Hash]
+    # {
+    #   "domain": "zerobounce.net",
+    #   "company_name": "Hertza, LLC",
+    #   "format": "first.last",
+    #   "confidence": "high",
+    #   "did_you_mean": "",
+    #   "failure_reason": "",
+    #   "other_domain_formats": [
+    #     {"format": "first", "confidence": "high"},
+    #     {"format": "last.first", "confidence": "high"},
+    #     {"format": "lastfirst", "confidence": "high"},
+    #     {"format": "firstl", "confidence": "high"},
+    #     {"format": "lfirst", "confidence": "high"},
+    #     {"format": "firstlast", "confidence": "high"},
+    #     {"format": "last_middle_f", "confidence": "high"},
+    #     {"format": "last", "confidence": "high"},
+    #     {"format": "f.last", "confidence": "medium"},
+    #     {"format": "last-f", "confidence": "medium"},
+    #     {"format": "l.first", "confidence": "medium"},
+    #     {"format": "last_f", "confidence": "medium"},
+    #     {"format": "first.middle.last", "confidence": "medium"},
+    #     {"format": "first-last", "confidence": "medium"},
+    #     {"format": "last.f", "confidence": "medium"},
+    #     {"format": "last_first", "confidence": "medium"},
+    #     {"format": "f-last", "confidence": "medium"},
+    #     {"format": "first.l", "confidence": "medium"},
+    #     {"format": "first-l", "confidence": "medium"},
+    #     {"format": "first_l", "confidence": "medium"},
+    #     {"format": "first_last", "confidence": "medium"},
+    #     {"format": "f_last", "confidence": "medium"},
+    #     {"format": "last-first", "confidence": "medium"},
+    #     {"format": "flast", "confidence": "medium"},
+    #     {"format": "lastf", "confidence": "medium"},
+    #     {"format": "l_first", "confidence": "medium"},
+    #     {"format": "l-first", "confidence": "medium"},
+    #     {"format": "first-middle-last", "confidence": "low"},
+    #     {"format": "firstmlast", "confidence": "low"},
+    #     {"format": "last.middle.first", "confidence": "low"},
+    #     {"format": "last_middle_first", "confidence": "low"},
+    #     {"format": "first_middle_last", "confidence": "low"},
+    #     {"format": "last-middle-first", "confidence": "low"},
+    #     {"format": "first-m-last", "confidence": "low"},
+    #     {"format": "firstmiddlelast", "confidence": "low"},
+    #     {"format": "last.m.first", "confidence": "low"},
+    #     {"format": "lastmfirst", "confidence": "low"},
+    #     {"format": "lastmiddlefirst", "confidence": "low"},
+    #     {"format": "last_m_first", "confidence": "low"},
+    #     {"format": "first.m.last", "confidence": "low"},
+    #     {"format": "first_m_last", "confidence": "low"},
+    #     {"format": "last-m-first", "confidence": "low"}
+    #   ]
+    # }
+    def find_domain(domain: '', company_name: '')
+      # Validate that exactly one of domain or company_name is provided
+      if (domain.nil? || domain.empty?) && (company_name.nil? || company_name.empty?)
+        raise ArgumentError, "Either domain or company_name must be provided"
+      elsif !(domain.nil? || domain.empty?) && !(company_name.nil? || company_name.empty?)
+        raise ArgumentError, "Only one of domain or company_name can be provided"
       end
 
+      params = {}
+      params[:domain] = domain unless domain.nil? || domain.empty?
+      params[:company_name] = company_name unless company_name.nil? || company_name.empty?
+
       @@request.get('guessformat', params)
     end
 

data/zerobounce.gemspec

@@ -27,8 +27,12 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.required_ruby_version = '>= 2.5'
 
   spec.add_dependency 'rest-client', '~>2.1'
-  spec.add_dependency 'dotenv', '~> 2.8.1'
+  spec.add_dependency 'dotenv'
 
+  spec.add_development_dependency 'base64' # stdlib gem on Ruby 3.4+
+  spec.add_development_dependency 'bigdecimal' # required by crack (webmock) on Ruby 3.4+
+  spec.add_development_dependency 'ostruct' # stdlib gem on Ruby 3.5+ (json/simplecov load chain)
+  spec.add_development_dependency 'logger' # stdlib gem on Ruby 3.4+ (mime-types / rest-client load chain)
   spec.add_development_dependency 'bundler', '~> 2.4.6'
   spec.add_development_dependency 'pry', '~> 0.14.1'
   spec.add_development_dependency 'rake', '~> 13.0'
@@ -39,7 +43,7 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.add_development_dependency 'rubocop-rake', '~> 0.5.1'
   spec.add_development_dependency 'rubocop-rspec', '~> 2.3'
   spec.add_development_dependency 'simplecov', '~> 0.21.2'
-  spec.add_development_dependency 'yard', '~> 0.9.26'
+  spec.add_development_dependency 'yard', '~> 0.9.42'
   spec.add_development_dependency 'webmock', '~> 3.18'
-  spec.add_development_dependency 'vcr', '~> 6.1.0'
+  spec.add_development_dependency 'vcr', '~> 6.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zerobounce-sdk
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 2.1.8
 platform: ruby
 authors:
 - Zero Bounce
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-06 00:00:00.000000000 Z
+date: 2026-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -28,16 +28,72 @@ dependencies:
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 2.8.1
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 2.8.1
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -190,14 +246,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.26
+        version: 0.9.42
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.26
+        version: 0.9.42
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -218,14 +274,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: '6.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: '6.4'
 description: A Ruby client for Zerobounce.net.
 email:
 - integrations@zerobounce.net
@@ -233,36 +289,50 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".env.sample"
+- ".dockerignore"
+- ".env.example"
+- ".github/auto_assign.yml"
+- ".github/dependabot.yml"
+- ".github/workflows/auto_assign_ci.yaml"
+- ".github/workflows/codeql.yml"
+- ".github/workflows/publish.yml"
+- ".github/workflows/sdk_ci.yml"
 - ".gitignore"
 - ".rspec"
 - ".ruby-version"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
+- Dockerfile
 - Gemfile
 - Gemfile.lock
 - LICENSE
 - LICENSE.txt
 - README.md
 - Rakefile
+- SECURITY.md
 - bin/bundle
 - bin/console
 - bin/setup
 - data/zerobounce-ai-scoring.csv
 - data/zerobounce-batch-validation.csv
 - documentation.md
-- documentation_es.md
 - files/scoring.csv
 - files/validation.csv
 - files/zerobounce-ai-scoring.csv
 - files/zerobounce-batch-validation.csv
 - lib/zerobounce.rb
+- lib/zerobounce/api_urls.rb
 - lib/zerobounce/base_request.rb
 - lib/zerobounce/configuration.rb
+- lib/zerobounce/download_type.rb
 - lib/zerobounce/error.rb
+- lib/zerobounce/get_file_helper.rb
+- lib/zerobounce/get_file_options.rb
 - lib/zerobounce/mock_request.rb
 - lib/zerobounce/request.rb
+- lib/zerobounce/validate_status.rb
+- lib/zerobounce/validate_sub_status.rb
 - lib/zerobounce/version.rb
 - zerobounce.gemspec
 homepage: https://zerobounce.net
@@ -270,7 +340,7 @@ licenses:
 - MIT
 metadata:
   yard.run: yri
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -285,8 +355,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
-signing_key: 
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: A Ruby client for Zerobounce.net.
 test_files: []

data/.env.sample

@@ -1,3 +0,0 @@
-ZEROBOUNCE_API_KEY=99e7ef20ceea4480a173b07b1be75371
-INCORRECT_API_KEY=thiskeyisinvalidorotherwiseincorrect
-TEST=unit