tomba 1.0.0 → 1.1.0

data/lib/tomba/services/leads-lists.rb

@@ -1,59 +1,84 @@
-module Tomba
-    class LeadsLists < Service
-
-        def get_lists()
-            path = '/leads_lists/{id}'
-
-            params = {}
-
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-        def delete_list_id(id:)
-            if id.nil?
-                raise Tomba::Exception.new('Missing required parameter: "id"')
-            end
-
-            path = '/leads_lists/{id}'
-                .gsub('{id}', id)
-
-            params = {}
-
-            return @client.call('delete', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-        def create_list()
-            path = '/leads_lists/{id}'
+# frozen_string_literal: true
 
-            params = {}
-
-            return @client.call('post', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-        def update_list_id(id:)
-            if id.nil?
-                raise Tomba::Exception.new('Missing required parameter: "id"')
-            end
-
-            path = '/leads_lists/{id}'
-                .gsub('{id}', id)
-
-            params = {}
-
-            return @client.call('put', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-
-        protected
-
-        private
-    end 
-end
+module Tomba
+  # Leads Lists service for managing lead lists.
+  #
+  # Provides methods to list, create, update, and delete lead lists.
+  #
+  # @see https://docs.tomba.io/api/leads-lists
+  class LeadsLists < Service
+    # List all leads lists.
+    #
+    # Returns all leads lists associated with the account.
+    #
+    # @see https://docs.tomba.io/api/leads-lists#list-leads-lists
+    # @return [Hash] API response containing the lists
+    # @raise [Tomba::Exception]
+    def get_lists
+      path = '/leads_lists'
+
+      params = {}
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Delete a leads list.
+    #
+    # Removes a specific leads list by its ID.
+    #
+    # @see https://docs.tomba.io/api/leads-lists#delete-leads-list
+    # @param id [String] the list ID to delete
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def delete_list_id(id:)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/leads_lists/#{id}"
+
+      params = {}
+
+      @client.call('delete', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Create a new leads list.
+    #
+    # Creates a new leads list for organizing leads.
+    #
+    # @see https://docs.tomba.io/api/leads-lists#create-leads-list
+    # @return [Hash] API response containing the new list
+    # @raise [Tomba::Exception]
+    def create_list
+      path = '/leads_lists'
+
+      params = {}
+
+      @client.call('post', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Update a leads list.
+    #
+    # Updates a specific leads list by its ID.
+    #
+    # @see https://docs.tomba.io/api/leads-lists#update-leads-list
+    # @param id [String] the list ID to update
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def update_list_id(id:)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/leads_lists/#{id}"
+
+      params = {}
+
+      @client.call('put', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/leads.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Tomba
+  # Leads service for managing individual leads.
+  #
+  # Provides methods to list, get, create, update, and delete leads.
+  #
+  # @see https://docs.tomba.io/api/leads
+  class Leads < Service
+    # List Leads
+    #
+    # Returns a paginated list of leads.
+    #
+    # @see https://docs.tomba.io/api/leads
+    # @param page [Integer, nil] the page number for pagination
+    # @param limit [Integer, nil] the number of results per page
+    # @param domain [String, nil] filter leads by domain
+    # @return [Hash] API response containing the list of leads
+    # @raise [Tomba::Exception]
+    def list_leads(page: nil, limit: nil, domain: nil)
+      path = '/leads'
+
+      params = {}
+      params[:page] = page unless page.nil?
+      params[:limit] = limit unless limit.nil?
+      params[:domain] = domain unless domain.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Get Lead
+    #
+    # Returns a specific lead by its ID.
+    #
+    # @see https://docs.tomba.io/api/leads#retrieve-a-single-lead
+    # @param id [String] the lead ID
+    # @return [Hash] API response containing the lead data
+    # @raise [Tomba::Exception]
+    def get_lead(id)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/leads/#{id}"
+
+      params = {}
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Create Lead
+    #
+    # Creates a new lead with the provided data.
+    #
+    # @see https://docs.tomba.io/api/leads#create-a-lead
+    # @param data [Hash] the lead data (e.g., email, first_name, last_name)
+    # @return [Hash] API response containing the created lead
+    # @raise [Tomba::Exception]
+    def create_lead(**data)
+      path = '/leads'
+
+      @client.call('post', path, {
+                     'content-type' => 'application/json'
+                   }, data)
+    end
+
+    # Update Lead
+    #
+    # Updates an existing lead by its ID.
+    #
+    # @see https://docs.tomba.io/api/leads#update-a-lead
+    # @param id [String] the lead ID to update
+    # @param data [Hash] the lead data to update
+    # @return [Hash] API response containing the updated lead
+    # @raise [Tomba::Exception]
+    def update_lead(id, **data)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/leads/#{id}"
+
+      @client.call('put', path, {
+                     'content-type' => 'application/json'
+                   }, data)
+    end
+
+    # Delete Lead
+    #
+    # Deletes a specific lead by its ID.
+    #
+    # @see https://docs.tomba.io/api/leads#delete-a-lead
+    # @param id [String] the lead ID to delete
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def delete_lead(id)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/leads/#{id}"
+
+      params = {}
+
+      @client.call('delete', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/location.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tomba
+  # Location service for retrieving company location data.
+  #
+  # Provides methods to get the geographic location associated with a domain.
+  #
+  # @see https://docs.tomba.io/api/finder#location
+  class Location < Service
+    # Get Location
+    #
+    # Returns the geographic location information for a given domain.
+    #
+    # @see https://docs.tomba.io/api/finder#location#get-location
+    # @param domain [String] the domain name to look up location for
+    # @return [Hash] API response containing location data
+    # @raise [Tomba::Exception]
+    def get_location(domain)
+      raise Tomba::Exception, 'Missing required parameter: "domain"' if domain.nil?
+
+      path = '/location'
+
+      params = { domain: domain }
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/logs.rb

@@ -1,19 +1,31 @@
-module Tomba
-    class Logs < Service
-
-        def get_logs()
-            path = '/logs'
-
-            params = {}
-
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
+# frozen_string_literal: true
 
+module Tomba
+  # Logs service for retrieving API request logs.
+  #
+  # Provides methods to get the history of API requests.
+  #
+  # @see https://docs.tomba.io/api/account#retrieve-api-logs
+  class Logs < Service
+    # Get Logs
+    #
+    # Returns the log history of API requests.
+    #
+    # @see https://docs.tomba.io/api/account#retrieve-api-logs#get-logs
+    # @param page [Integer, nil] the page number for pagination
+    # @param limit [Integer, nil] the number of results per page
+    # @return [Hash] API response containing log entries
+    # @raise [Tomba::Exception]
+    def get_logs(page: nil, limit: nil)
+      path = '/logs'
 
-        protected
+      params = {}
+      params[:page] = page unless page.nil?
+      params[:limit] = limit unless limit.nil?
 
-        private
-    end 
-end
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/phone.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Tomba
+  # Phone service for phone number lookup and validation.
+  #
+  # Provides methods to find and validate phone numbers.
+  #
+  # @see https://docs.tomba.io/api/phone
+  class Phone < Service
+    # Phone Finder
+    #
+    # Finds a phone number using search parameters.
+    #
+    # @see https://docs.tomba.io/api/phone#phone-finder
+    # @param params [Hash] search parameters (e.g., email, domain)
+    # @param webhook_url [String, nil] webhook URL for async notifications
+    # @return [Hash] API response containing phone number data
+    # @raise [Tomba::Exception]
+    def finder(params, webhook_url: nil)
+      raise Tomba::Exception, 'Missing required parameter: "params"' if params.nil? || params.empty?
+
+      path = '/phone-finder'
+
+      params[:webhook_url] = webhook_url unless webhook_url.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Phone Validator
+    #
+    # Validates a phone number and returns detailed information about it.
+    #
+    # @see https://docs.tomba.io/api/phone#phone-validator
+    # @param phone [String] the phone number to validate
+    # @param country_code [String, nil] optional ISO country code (e.g., "US")
+    # @return [Hash] API response containing validation results
+    # @raise [Tomba::Exception]
+    def validator(phone, country_code: nil)
+      raise Tomba::Exception, 'Missing required parameter: "phone"' if phone.nil?
+
+      path = '/phone-validator'
+
+      params = { phone: phone }
+      params[:country_code] = country_code unless country_code.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/reveal.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Tomba
+  # Reveal service for company search.
+  #
+  # Provides methods to search for companies.
+  #
+  # @see https://docs.tomba.io/api/reveal
+  class Reveal < Service
+    # Companies Search
+    #
+    # Searches for companies matching the given parameters.
+    #
+    # @see https://docs.tomba.io/api/reveal#companies-search
+    # @param params [Hash] search parameters (e.g., query, page, limit)
+    # @return [Hash] API response containing matching companies
+    # @raise [Tomba::Exception]
+    def companies_search(params)
+      raise Tomba::Exception, 'Missing required parameter: "params"' if params.nil? || params.empty?
+
+      path = '/reveal'
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/similar.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tomba
+  # Similar service for finding similar websites.
+  #
+  # Provides methods to find websites similar to a given domain.
+  #
+  # @see https://docs.tomba.io/api/similar
+  class Similar < Service
+    # Similar Websites
+    #
+    # Returns a list of websites similar to the given domain.
+    #
+    # @see https://docs.tomba.io/api/similar#similar-websites
+    # @param domain [String] the domain name to find similar websites for
+    # @return [Hash] API response containing similar websites
+    # @raise [Tomba::Exception]
+    def websites(domain)
+      raise Tomba::Exception, 'Missing required parameter: "domain"' if domain.nil?
+
+      path = '/similar'
+
+      params = { domain: domain }
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/sources.rb

@@ -1,24 +1,31 @@
-module Tomba
-    class Sources < Service
-
-        def email_sources(email:)
-            if email.nil?
-                raise Tomba::Exception.new('Missing required parameter: "email"')
-            end
-
-            path = '/email-sources/{email}'
-                .gsub('{email}', email)
+# frozen_string_literal: true
 
-            params = {}
-
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
+module Tomba
+  # Sources service for finding email sources.
+  #
+  # Provides methods to retrieve the sources where an email was found.
+  #
+  # @see https://docs.tomba.io/api/sources
+  class Sources < Service
+    # Email Sources
+    #
+    # Retrieves the sources where an email address has been found on the web.
+    #
+    # @see https://docs.tomba.io/api/sources#email-sources
+    # @param email [String] the email address to look up sources for
+    # @return [Hash] API response containing source information
+    # @raise [Tomba::Exception]
+    def email_sources(email:)
+      raise Tomba::Exception, 'Missing required parameter: "email"' if email.nil?
 
+      path = '/email-sources'
 
-        protected
+      params = {}
+      params[:email] = email unless email.nil?
 
-        private
-    end 
-end
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/status.rb

@@ -1,45 +1,52 @@
-module Tomba
-    class Status < Service
-
-        def domain_status(domain:)
-            if domain.nil?
-                raise Tomba::Exception.new('Missing required parameter: "domain"')
-            end
-
-            path = '/domain-status'
-
-            params = {}
-
-            if !domain.nil?
-                params[:domain] = domain
-            end
-
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-        def auto_complete(query:)
-            if query.nil?
-                raise Tomba::Exception.new('Missing required parameter: "query"')
-            end
+# frozen_string_literal: true
 
-            path = '/domains-suggestion'
-
-            params = {}
-
-            if !query.nil?
-                params[:query] = query
-            end
-
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-
-        protected
-
-        private
-    end 
-end
+module Tomba
+  # Status service for domain status and autocomplete.
+  #
+  # Provides methods to check domain status and get domain suggestions.
+  #
+  # @see https://docs.tomba.io/api/status
+  class Status < Service
+    # Domain Status
+    #
+    # Returns the status of a domain, including whether it is webmail or disposable.
+    #
+    # @see https://docs.tomba.io/api/status#domain-status
+    # @param domain [String] the domain name to check
+    # @return [Hash] API response containing domain status
+    # @raise [Tomba::Exception]
+    def domain_status(domain:)
+      raise Tomba::Exception, 'Missing required parameter: "domain"' if domain.nil?
+
+      path = '/domain-status'
+
+      params = {}
+      params[:domain] = domain unless domain.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Autocomplete
+    #
+    # Returns domain suggestions based on a search query.
+    #
+    # @see https://docs.tomba.io/api/status#domain-suggestions
+    # @param query [String] the search query for domain suggestions
+    # @return [Hash] API response containing domain suggestions
+    # @raise [Tomba::Exception]
+    def auto_complete(query:)
+      raise Tomba::Exception, 'Missing required parameter: "query"' if query.nil?
+
+      path = '/domain-suggestions'
+
+      params = {}
+      params[:query] = query unless query.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/technology.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tomba
+  # Technology service for detecting website technologies.
+  #
+  # Provides methods to discover the technologies used by a website.
+  #
+  # @see https://docs.tomba.io/api/domain#technology
+  class Technology < Service
+    # List Technologies
+    #
+    # Returns the technologies detected on a given domain.
+    #
+    # @see https://docs.tomba.io/api/domain#technology#list-technologies
+    # @param domain [String] the domain name to analyze
+    # @return [Hash] API response containing detected technologies
+    # @raise [Tomba::Exception]
+    def list(domain)
+      raise Tomba::Exception, 'Missing required parameter: "domain"' if domain.nil?
+
+      path = '/technology'
+
+      params = { domain: domain }
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/usage.rb

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