tomba 1.0.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48d74ce103c86637e8f0f5293ab01e48be49d399644117f105a1cec48a6c9281
-  data.tar.gz: a525655fea90a69604ae4a4eb8beda7741905ffaec39453e7e7a983a1d089704
+  metadata.gz: 8ff6ec0d9448e445df78fd5bf6c07ef6793ed9f91c00be2796d4465c8a0f25a2
+  data.tar.gz: b18b046b50cdef9e1ab9683614e5ec01de2a221ef8b5cec86a8ce9613b2f693b
 SHA512:
-  metadata.gz: bdd91773b2a06692e95a6f6323ef6c323825ad9ae0ebbf6175d7a5098e25230a31ee9f89eed943d69997511ac17fa1d47c18935d8128d636cf22790c7b109429
-  data.tar.gz: 0ba6101c444eb0f8a993cba1387813a19bcd532f07a7e1e549f0c5c009e73a9a7f8015cdfeb2f5299e1792f119ee98e568b2b7566e3eea86db0a3f1e50e7ebb9
+  metadata.gz: '067991e7633f6fba45b7c679bbdce417e59065278fe7d780c31b30aa1028b2fe7254cba3a7cebf452272b2e1bfe08c818553612bd6f62c51fb57040f657dd14c'
+  data.tar.gz: 618f4040dcd9b973c18243138f3c37302ac895b85494fbe9c6f55914579ec4e1e0abd9ffd49464f043b5b9141981d2ba30e3ba29170eb28cb104e8a6b37839ce

data/lib/tomba/client.rb

@@ -1,122 +1,168 @@
+# frozen_string_literal: true
+
 require 'net/http'
 require 'uri'
 require 'json'
 require 'cgi'
 
 module Tomba
-    class Client
+  class Client
+    METHOD_GET = 'get'
+    METHOD_POST = 'post'
+    METHOD_PUT = 'put'
+    METHOD_PATCH = 'patch'
+    METHOD_DELETE = 'delete'
+    METHOD_HEAD = 'head'
+    METHOD_OPTIONS = 'options'
+    METHOD_CONNECT = 'connect'
+    METHOD_TRACE = 'trace'
+
+    def initialize
+      @headers = {
+        'content-type' => '',
+        'user-agent' => "#{RUBY_PLATFORM}:ruby-#{RUBY_VERSION}",
+        'x-sdk-version' => "tomba:ruby:v#{Tomba::VERSION}"
+
+      }
+      @endpoint = 'https://api.tomba.io/v1'
+    end
+
+    def set_key(value)
+      add_header('x-tomba-key', value)
+
+      self
+    end
+
+    def set_secret(value)
+      add_header('x-tomba-secret', value)
+
+      self
+    end
+
+    def set_endpoint(endpoint)
+      @endpoint = endpoint
+
+      self
+    end
+
+    def add_header(key, value)
+      @headers[key.downcase] = value
+
+      self
+    end
+
+    def call(method, path = '', headers = {}, params = {})
+      uri = URI.parse(@endpoint + path + (method == METHOD_GET && params.length ? "?#{encode(params)}" : ''))
+      fetch(method, uri, headers, params)
+    end
+
+    def call_raw(method, path = '', headers = {}, params = {})
+      uri = URI.parse(@endpoint + path + (method == METHOD_GET && params.length ? "?#{encode(params)}" : ''))
+      fetch_raw(method, uri, headers, params)
+    end
+
+    private
+
+    def fetch(method, uri, headers, params, limit = 5)
+      raise ArgumentError, 'Too Many HTTP Redirects' if limit.zero?
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+      http.read_timeout = 120
+      http.open_timeout = 120
+      payload = ''
+
+      headers = @headers.merge(headers)
+      @boundary = '----A30#3ad1'
+      if method != METHOD_GET
+        payload = case headers['content-type'][0,
+                                               headers['content-type'].index(';') || headers['content-type'].length]
+                  when 'application/json'
+                    params.to_json
+                  else
+                    encode(params)
+                  end
+      end
+
+      begin
+        response = http.send_request(method.upcase, uri.request_uri, payload, headers)
+      rescue StandardError => e
+        raise Tomba::Exception, e.message
+      end
+
+      # Handle Redirects
+      if response.instance_of?(Net::HTTPRedirection) || response.instance_of?(Net::HTTPMovedPermanently)
+        location = response['location']
+        uri = URI.parse("#{uri.scheme}://#{uri.host}#{location}")
+
+        return fetch(method, uri, headers, {}, limit - 1)
+      end
+
+      begin
+        res = JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise Tomba::Exception.new(response.body, response.code, nil)
+      end
+
+      raise Tomba::Exception.new(res['errors']['message'], res['errors']['code'], res) if response.code.to_i >= 400
+
+      { 'data' => res, 'rate_limit' => parse_rate_limit(response) }
+    end
+
+    def fetch_raw(method, uri, headers, _params, limit = 5)
+      raise ArgumentError, 'Too Many HTTP Redirects' if limit.zero?
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+      http.read_timeout = 120
+      http.open_timeout = 120
+
+      headers = @headers.merge(headers)
+
+      begin
+        response = http.send_request(method.upcase, uri.request_uri, '', headers)
+      rescue StandardError => e
+        raise Tomba::Exception, e.message
+      end
+
+      if response.instance_of?(Net::HTTPRedirection) || response.instance_of?(Net::HTTPMovedPermanently)
+        location = response['location']
+        uri = URI.parse("#{uri.scheme}://#{uri.host}#{location}")
+        return fetch_raw(method, uri, headers, {}, limit - 1)
+      end
+
+      raise Tomba::Exception.new(response.body, response.code, nil) if response.code.to_i >= 400
+
+      { 'data' => response.body, 'rate_limit' => parse_rate_limit(response) }
+    end
+
+    def parse_rate_limit(response)
+      {
+        'x-second-rate-limit' => response['x-second-rate-limit']&.to_i,
+        'x-minute-rate-limit' => response['x-minute-rate-limit']&.to_i,
+        'x-daily-rate-limit' => response['x-daily-rate-limit']&.to_i,
+        'x-minute-request-left' => response['x-minute-request-left']&.to_i,
+        'x-daily-request-left' => response['x-daily-request-left']&.to_i,
+        'x-minute-reset-seconds' => response['x-minute-reset-seconds']&.to_i,
+        'x-daily-reset-seconds' => response['x-daily-reset-seconds']&.to_i,
+        'retry-after' => response['retry-after']&.to_i,
+        'ratelimit-policy' => response['ratelimit-policy'],
+        'ratelimit' => response['ratelimit']
+      }
+    end
+
+    def encode(value, key = nil)
+      case value
+      when Hash  then value.map { |k, v| encode(v, append_key(key, k)) }.join('&')
+      when Array then value.map { |v| encode(v, "#{key}[]") }.join('&')
+      when nil   then ''
+      else
+        "#{key}=#{CGI.escape(value.to_s)}"
+      end
+    end
 
-        METHOD_GET = 'get'
-        METHOD_POST = 'post'
-        METHOD_PUT = 'put'
-        METHOD_PATCH = 'patch'
-        METHOD_DELETE = 'delete'
-        METHOD_HEAD = 'head'
-        METHOD_OPTIONS = 'options'
-        METHOD_CONNECT = 'connect'
-        METHOD_TRACE = 'trace'
-
-        def initialize()
-            @headers = {
-                'content-type' => '',
-                'user-agent' => RUBY_PLATFORM + ':ruby-' + RUBY_VERSION,
-                'x-sdk-version' => 'tomba:ruby:v1.0.1'
-
-            }
-            @endpoint = 'https://api.tomba.io/v1';
-        end
-
-        def set_key(value)
-            add_header('x-tomba-key', value)
-
-            return self
-        end
-
-        def set_secret(value)
-            add_header('x-tomba-secret', value)
-
-            return self
-        end
-
-        def set_endpoint(endpoint)
-            @endpoint = endpoint
-
-            return self
-        end
-
-        def add_header(key, value)
-            @headers[key.downcase] = value
-
-            return self
-        end
-
-        def call(method, path = '', headers = {}, params = {})
-            uri = URI.parse(@endpoint + path + ((method == METHOD_GET && params.length) ? '?' + encode(params) : ''))
-            return fetch(method, uri, headers, params)
-        end
-
-        protected
-
-        private
-
-        def fetch(method, uri, headers, params, limit = 5)
-            raise ArgumentError, 'Too Many HTTP Redirects' if limit == 0
-
-            http = Net::HTTP.new(uri.host, uri.port)
-            http.use_ssl = (uri.scheme == 'https')
-            payload = ''
-
-            headers = @headers.merge(headers)
-            @BOUNDARY = "----A30#3ad1"
-            if (method != METHOD_GET)
-                case headers['content-type'][0, headers['content-type'].index(';') || headers['content-type'].length]
-                    when 'application/json'
-                        payload = params.to_json
-                    else
-                        payload = encode(params)
-                end
-            end
-
-            begin
-                response = http.send_request(method.upcase, uri.request_uri, payload, headers)
-            rescue => error
-                raise Tomba::Exception.new(error.message)
-            end
-
-            # Handle Redirects
-            if (response.class == Net::HTTPRedirection || response.class == Net::HTTPMovedPermanently)
-                location = response['location']
-                uri = URI.parse(uri.scheme + "://" + uri.host + "" + location)
-
-                return fetch(method, uri, headers, {}, limit - 1)
-            end
-
-            begin
-                res = JSON.parse(response.body);
-            rescue JSON::ParserError => e
-                raise Tomba::Exception.new(response.body, response.code, nil)
-            end
-
-            if(response.code.to_i >= 400)
-                raise Tomba::Exception.new(res['errors']['message'], res['errors']['code'], res)
-            end
-
-            return res;
-        end
-
-
-        def encode(value, key = nil)
-            case value
-            when Hash  then value.map { |k,v| encode(v, append_key(key,k)) }.join('&')
-            when Array then value.map { |v| encode(v, "#{key}[]") }.join('&')
-            when nil   then ''
-            else
-            "#{key}=#{CGI.escape(value.to_s)}"
-            end
-        end
-
-        def append_key(root_key, key)
-            root_key.nil? ? key : "#{root_key}[#{key.to_s}]"
-        end
+    def append_key(root_key, key)
+      root_key.nil? ? key : "#{root_key}[#{key}]"
     end
+  end
 end

data/lib/tomba/exception.rb

@@ -1,14 +1,23 @@
-module Tomba
-    class Exception < StandardError
-        @code = 0;
-        @response = nil;
+# frozen_string_literal: true
 
-        def initialize(message, code, response)
-            super(message)
-            @code = code
-            @response = response
-        end
-        attr_reader :code
-        attr_reader :response
+module Tomba
+  # Custom exception class for Tomba API errors.
+  #
+  # Raised when the API returns an error response or when
+  # required parameters are missing.
+  #
+  # @attr_reader code [Integer, nil] the HTTP status code or error code
+  # @attr_reader response [Hash, nil] the full error response body
+  class Exception < StandardError
+    # @param message [String] the error message
+    # @param code [Integer, nil] the HTTP status code or error code
+    # @param response [Hash, nil] the full error response body
+    def initialize(message, code = nil, response = nil)
+      super(message)
+      @code = code
+      @response = response
     end
+
+    attr_reader :code, :response
+  end
 end

data/lib/tomba/service.rb

@@ -1,12 +1,16 @@
-module Tomba
-    class Service
-
-        def initialize(client)
-            @client = client
-        end
-        
-        protected
+# frozen_string_literal: true
 
-        private
-    end 
-end
+module Tomba
+  # Base service class.
+  #
+  # All Tomba service classes inherit from this base class,
+  # which provides access to the API client.
+  class Service
+    # Initialize the service with a Tomba client.
+    #
+    # @param client [Tomba::Client] the API client instance
+    def initialize(client)
+      @client = client
+    end
+  end
+end

data/lib/tomba/services/account.rb

@@ -1,19 +1,27 @@
-module Tomba
-    class Account < Service
-
-        def get_account()
-            path = '/me'
-
-            params = {}
-
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
+# frozen_string_literal: true
 
+module Tomba
+  # Account service for retrieving account information.
+  #
+  # Provides methods to get the current account details.
+  #
+  # @see https://docs.tomba.io/api/account
+  class Account < Service
+    # Get Account
+    #
+    # Returns information about the current account.
+    #
+    # @see https://docs.tomba.io/api/account#get-account
+    # @return [Hash] API response containing account details
+    # @raise [Tomba::Exception]
+    def get_account
+      path = '/me'
 
-        protected
+      params = {}
 
-        private
-    end 
-end
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/bulk.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module Tomba
+  # Bulk service for managing bulk operations.
+  #
+  # Provides methods to list, get, create, launch, delete, archive,
+  # rename, check progress, and download bulk tasks.
+  #
+  # @see https://docs.tomba.io/api/bulk
+  class Bulk < Service
+    VALID_TYPES = %w[search similar company finder enrich linkedin author verifier phone-finder phone-validator].freeze
+
+    # Validate the bulk type parameter.
+    #
+    # @param type [String] the bulk type to validate
+    # @raise [Tomba::Exception] if the type is not valid
+    def validate_type(type)
+      return if VALID_TYPES.include?(type)
+
+      raise Tomba::Exception, "Invalid bulk type: \"#{type}\". Must be one of: #{VALID_TYPES.join(', ')}"
+    end
+
+    # List Bulk Tasks
+    #
+    # Returns a list of bulk tasks of the specified type.
+    #
+    # @see https://docs.tomba.io/api/bulks-tasks
+    # @param type [String] the bulk task type (e.g., "searches", "verifiers")
+    # @param params [Hash] optional query parameters for filtering
+    # @return [Hash] API response containing the list of bulk tasks
+    # @raise [Tomba::Exception]
+    def list(type, params: {})
+      raise Tomba::Exception, 'Missing required parameter: "type"' if type.nil?
+
+      validate_type(type)
+
+      path = "/bulk/#{type}"
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Get Bulk Task
+    #
+    # Returns a specific bulk task by type and ID.
+    #
+    # @see https://docs.tomba.io/api/bulk#get-bulk-task
+    # @param type [String] the bulk task type
+    # @param id [String] the bulk task ID
+    # @return [Hash] API response containing the bulk task data
+    # @raise [Tomba::Exception]
+    def get(type, id)
+      raise Tomba::Exception, 'Missing required parameter: "type"' if type.nil?
+
+      validate_type(type)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/bulk/#{type}/#{id}"
+
+      params = {}
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Create Bulk Task
+    #
+    # Creates a new bulk task of the specified type.
+    #
+    # @see https://docs.tomba.io/api/bulks
+    # @param type [String] the bulk task type
+    # @param data [Hash] the bulk task data
+    # @return [Hash] API response containing the created bulk task
+    # @raise [Tomba::Exception]
+    def create(type, data)
+      raise Tomba::Exception, 'Missing required parameter: "type"' if type.nil?
+
+      validate_type(type)
+
+      path = "/bulk/#{type}"
+
+      @client.call('post', path, {
+                     'content-type' => 'application/json'
+                   }, data)
+    end
+
+    # Launch Bulk Task
+    #
+    # Launches (starts) a bulk task by type and ID.
+    #
+    # @see https://docs.tomba.io/api/bulks
+    # @param type [String] the bulk task type
+    # @param id [String] the bulk task ID
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def launch(type, id)
+      raise Tomba::Exception, 'Missing required parameter: "type"' if type.nil?
+
+      validate_type(type)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/bulk/#{type}/#{id}"
+
+      params = {}
+
+      @client.call('put', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Delete Bulk Task
+    #
+    # Deletes a bulk task by type and ID.
+    #
+    # @see https://docs.tomba.io/api/bulks
+    # @param type [String] the bulk task type
+    # @param id [String] the bulk task ID
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def delete(type, id)
+      raise Tomba::Exception, 'Missing required parameter: "type"' if type.nil?
+
+      validate_type(type)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/bulk/#{type}/#{id}/delete"
+
+      params = {}
+
+      @client.call('delete', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Archive Bulk Task
+    #
+    # Archives a bulk task by type and ID.
+    #
+    # @see https://docs.tomba.io/api/bulks
+    # @param type [String] the bulk task type
+    # @param id [String] the bulk task ID
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def archive(type, id)
+      raise Tomba::Exception, 'Missing required parameter: "type"' if type.nil?
+
+      validate_type(type)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/bulk/#{type}/#{id}/archive"
+
+      params = {}
+
+      @client.call('delete', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Rename Bulk Task
+    #
+    # Renames a bulk task by type and ID.
+    #
+    # @see https://docs.tomba.io/api/bulks
+    # @param type [String] the bulk task type
+    # @param id [String] the bulk task ID
+    # @param name [String] the new name for the bulk task
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def rename(type, id, name)
+      raise Tomba::Exception, 'Missing required parameter: "type"' if type.nil?
+
+      validate_type(type)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+      raise Tomba::Exception, 'Missing required parameter: "name"' if name.nil?
+
+      path = "/bulk/#{type}/#{id}/rename"
+
+      params = { name: name }
+
+      @client.call('put', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Bulk Task Progress
+    #
+    # Returns the progress status of a bulk task.
+    #
+    # @see https://docs.tomba.io/api/bulk#bulk-task-progress
+    # @param type [String] the bulk task type
+    # @param id [String] the bulk task ID
+    # @return [Hash] API response containing progress data
+    # @raise [Tomba::Exception]
+    def progress(type, id)
+      raise Tomba::Exception, 'Missing required parameter: "type"' if type.nil?
+
+      validate_type(type)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/bulk/#{type}/#{id}/progress"
+
+      params = {}
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Download Bulk Task
+    #
+    # Downloads the results of a completed bulk task.
+    #
+    # @see https://docs.tomba.io/api/bulks
+    # @param type [String] the bulk task type
+    # @param id [String] the bulk task ID
+    # @return [Hash] API response containing download data
+    # @raise [Tomba::Exception]
+    def download(type, id)
+      raise Tomba::Exception, 'Missing required parameter: "type"' if type.nil?
+
+      validate_type(type)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/bulk/#{type}/#{id}/download"
+
+      params = {}
+
+      @client.call_raw('get', path, {
+                         'content-type' => 'application/json'
+                       }, params)
+    end
+  end
+end

data/lib/tomba/services/count.rb

@@ -1,27 +1,31 @@
-module Tomba
-    class Count < Service
-
-        def email_count(domain:)
-            if domain.nil?
-                raise Tomba::Exception.new('Missing required parameter: "domain"')
-            end
-
-            path = '/email-count'
-
-            params = {}
-
-            if !domain.nil?
-                params[:domain] = domain
-            end
+# frozen_string_literal: true
 
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-
-        protected
-
-        private
-    end 
-end
+module Tomba
+  # Count service for email counting.
+  #
+  # Provides methods to get the number of email addresses found for a domain.
+  #
+  # @see https://docs.tomba.io/api/count
+  class Count < Service
+    # Email Count
+    #
+    # Returns the total number of email addresses found for a domain.
+    #
+    # @see https://docs.tomba.io/api/count#email-count
+    # @param domain [String] the domain name to count emails for
+    # @return [Hash] API response containing the email count
+    # @raise [Tomba::Exception]
+    def email_count(domain:)
+      raise Tomba::Exception, 'Missing required parameter: "domain"' if domain.nil?
+
+      path = '/email-count'
+
+      params = {}
+      params[:domain] = domain unless domain.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end