tomba 1.0.1 → 1.1.0

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

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

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