tomba 1.0.1 → 1.1.0

data/lib/tomba/services/domain.rb

@@ -1,39 +1,42 @@
-module Tomba
-    class Domain < Service
-
-        def domain_search(domain:, page: nil, limit: nil, department: nil)
-            if domain.nil?
-                raise Tomba::Exception.new('Missing required parameter: "domain"')
-            end
-
-            path = '/domain-search/'
-
-            params = {}
-
-            if !domain.nil?
-                params[:domain] = domain
-            end
-
-            if !page.nil?
-                params[:page] = page
-            end
+# frozen_string_literal: true
 
-            if !limit.nil?
-                params[:limit] = limit
-            end
-
-            if !department.nil?
-                params[:department] = department
-            end
-
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-
-        protected
-
-        private
+module Tomba
+  # Domain Search service.
+  #
+  # Search emails associated with a domain.
+  #
+  # @see https://docs.tomba.io/api/finder#domain-search
+  class Domain < Service
+    # Domain Search
+    #
+    # Returns all email addresses found for a given domain.
+    #
+    # @see https://docs.tomba.io/api/finder#domain-search#domain-search
+    # @param domain [String] the domain name to search
+    # @param page [Integer, nil] the page number for pagination
+    # @param limit [Integer, nil] the number of results per page
+    # @param department [String, nil] filter by department
+    # @param enrich_mobile [Boolean, nil] whether to enrich mobile phone data
+    # @param webhook_url [String, nil] webhook URL for async notifications
+    # @return [Hash] API response containing the list of emails
+    # @raise [Tomba::Exception]
+    def domain_search(domain:, page: nil, limit: nil, department: nil, enrich_mobile: nil, webhook_url: nil)
+      raise Tomba::Exception, 'Missing required parameter: "domain"' if domain.nil?
+
+      path = '/domain-search/'
+
+      params = {}
+
+      params[:domain] = domain unless domain.nil?
+      params[:page] = page unless page.nil?
+      params[:limit] = limit unless limit.nil?
+      params[:department] = department unless department.nil?
+      params[:enrich_mobile] = enrich_mobile unless enrich_mobile.nil?
+      params[:webhook_url] = webhook_url unless webhook_url.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
     end
+  end
 end

data/lib/tomba/services/enrichment.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Tomba
+  # Enrichment service for data enrichment.
+  #
+  # Provides methods to enrich person and company data.
+  #
+  # @see https://docs.tomba.io/api/enrichment
+  class Enrichment < Service
+    # Person Enrichment
+    #
+    # Enriches data about a person using their email address.
+    #
+    # @see https://docs.tomba.io/api/enrichment#person-enrichment
+    # @param email [String] the email address of the person
+    # @param webhook_url [String, nil] webhook URL for async notifications
+    # @return [Hash] API response containing enriched person data
+    # @raise [Tomba::Exception]
+    def person(email, webhook_url: nil)
+      raise Tomba::Exception, 'Missing required parameter: "email"' if email.nil?
+
+      path = '/enrichment/person'
+
+      params = { email: email }
+      params[:webhook_url] = webhook_url unless webhook_url.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Company Enrichment
+    #
+    # Enriches data about a company using its domain name.
+    #
+    # @see https://docs.tomba.io/api/enrichment#company-enrichment
+    # @param domain [String] the domain name of the company
+    # @return [Hash] API response containing enriched company data
+    # @raise [Tomba::Exception]
+    def company(domain)
+      raise Tomba::Exception, 'Missing required parameter: "domain"' if domain.nil?
+
+      path = '/enrichment/company'
+
+      params = { domain: domain }
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Combined Enrichment
+    #
+    # Returns combined person and company enrichment data for an email.
+    #
+    # @see https://docs.tomba.io/api/enrichment#combined-enrichment
+    # @param email [String] the email address to enrich
+    # @return [Hash] API response containing combined enrichment data
+    # @raise [Tomba::Exception]
+    def combined(email)
+      raise Tomba::Exception, 'Missing required parameter: "email"' if email.nil?
+
+      path = '/enrichment/combined'
+
+      params = { email: email }
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/finder.rb

@@ -1,95 +1,109 @@
-module Tomba
-    class Finder < Service
-
-        def email_finder(domain:, first_name:, last_name:)
-            if domain.nil?
-                raise Tomba::Exception.new('Missing required parameter: "domain"')
-            end
-
-            if first_name.nil?
-                raise Tomba::Exception.new('Missing required parameter: "firstName"')
-            end
-
-            if last_name.nil?
-                raise Tomba::Exception.new('Missing required parameter: "lastName"')
-            end
-
-            path = '/email-finder'
-
-            params = {}
-
-            if !domain.nil?
-                params[:domain] = domain
-            end
-
-            if !first_name.nil?
-                params[:first_name] = first_name
-            end
-
-            if !last_name.nil?
-                params[:last_name] = last_name
-            end
-
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-        def author_finder(url:)
-            if url.nil?
-                raise Tomba::Exception.new('Missing required parameter: "url"')
-            end
-
-            path = '/author-finder'
-
-            params = {}
-
-            if !url.nil?
-                params[:url] = url
-            end
+# frozen_string_literal: true
 
+module Tomba
+  # Finder service for email, author, LinkedIn, and phone lookups.
+  #
+  # Provides methods to find email addresses, authors, LinkedIn profiles,
+  # and phone numbers.
+  #
+  # @see https://docs.tomba.io/api/finder
+  class Finder < Service
+    # Email Finder
+    #
+    # Generates or retrieves the most likely email address from a domain and name.
+    #
+    # @see https://docs.tomba.io/api/finder#email-finder
+    # @param domain [String] the domain name
+    # @param first_name [String] the first name of the person
+    # @param last_name [String] the last name of the person
+    # @param webhook_url [String, nil] webhook URL for async notifications
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def email_finder(domain:, first_name:, last_name:, webhook_url: nil)
+      raise Tomba::Exception, 'Missing required parameter: "domain"' if domain.nil?
+      raise Tomba::Exception, 'Missing required parameter: "first_name"' if first_name.nil?
+      raise Tomba::Exception, 'Missing required parameter: "last_name"' if last_name.nil?
+
+      path = '/email-finder'
+
+      params = {}
+      params[:domain] = domain unless domain.nil?
+      params[:first_name] = first_name unless first_name.nil?
+      params[:last_name] = last_name unless last_name.nil?
+      params[:webhook_url] = webhook_url unless webhook_url.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
 
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-        def linkedin_finder(url:)
-            if url.nil?
-                raise Tomba::Exception.new('Missing required parameter: "url"')
-            end
-
-            path = '/linkedin-finder'
-
-            params = {}
-
-            if !url.nil?
-                params[:url] = url
-            end
-
-
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-        def phone_finder(email:)
-            if email.nil?
-                raise Tomba::Exception.new('Missing required parameter: "email"')
-            end
-
-            path = '/phone/{email}'
-                .gsub('{email}', email)
-
-            params = {}
-
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
+    # Author Finder
+    #
+    # Retrieves the email address of the author of a given article URL.
+    #
+    # @see https://docs.tomba.io/api/finder#author-finder
+    # @param url [String] the URL of the article
+    # @param webhook_url [String, nil] webhook URL for async notifications
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def author_finder(url:, webhook_url: nil)
+      raise Tomba::Exception, 'Missing required parameter: "url"' if url.nil?
+
+      path = '/author-finder'
+
+      params = {}
+      params[:url] = url unless url.nil?
+      params[:webhook_url] = webhook_url unless webhook_url.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
 
-        protected
+    # LinkedIn Finder
+    #
+    # Retrieves the email address of a person from their LinkedIn URL.
+    #
+    # @see https://docs.tomba.io/api/finder#linkedin-finder
+    # @param url [String] the LinkedIn profile URL
+    # @param webhook_url [String, nil] webhook URL for async notifications
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def linkedin_finder(url:, webhook_url: nil)
+      raise Tomba::Exception, 'Missing required parameter: "url"' if url.nil?
+
+      path = '/linkedin-finder'
+
+      params = {}
+      params[:url] = url unless url.nil?
+      params[:webhook_url] = webhook_url unless webhook_url.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
 
-        private
+    # Phone Finder
+    #
+    # Retrieves the phone number associated with an email address.
+    #
+    # @see https://docs.tomba.io/api/finder#phone-finder
+    # @param email [String] the email address to look up
+    # @param webhook_url [String, nil] webhook URL for async notifications
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def phone_finder(email:, webhook_url: nil)
+      raise Tomba::Exception, 'Missing required parameter: "email"' if email.nil?
+
+      path = '/phone-finder'
+
+      params = {}
+      params[:email] = email unless email.nil?
+      params[:webhook_url] = webhook_url unless webhook_url.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
     end
+  end
 end

data/lib/tomba/services/flag.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Tomba
+  # Flag service for managing email flags.
+  #
+  # Provides methods to list and create flags for email addresses.
+  #
+  # @see https://docs.tomba.io/api/flag
+  class Flag < Service
+    # List Flags
+    #
+    # Returns all flags associated with the account.
+    #
+    # @see https://docs.tomba.io/api/flag#list-flags
+    # @param page [Integer, nil] the page number for pagination
+    # @param limit [Integer, nil] the number of results per page
+    # @return [Hash] API response containing the list of flags
+    # @raise [Tomba::Exception]
+    def list_flags(page: nil, limit: nil)
+      path = '/flags'
+
+      params = {}
+      params[:page] = page unless page.nil?
+      params[:limit] = limit unless limit.nil?
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Create Flag
+    #
+    # Creates a new flag for an email address.
+    #
+    # @see https://docs.tomba.io/api/flag#create-flag
+    # @param email [String] the email address to flag
+    # @param reason [String, nil] optional reason for the flag
+    # @return [Hash] API response containing the created flag
+    # @raise [Tomba::Exception]
+    def create_flag(email:, reason: nil)
+      raise Tomba::Exception, 'Missing required parameter: "email"' if email.nil?
+
+      path = '/flags'
+
+      params = { email: email }
+      params[:reason] = reason unless reason.nil?
+
+      @client.call('post', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/format.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tomba
+  # Format service for discovering email formats.
+  #
+  # Provides methods to find the email format used by a domain.
+  #
+  # @see https://docs.tomba.io/api/format
+  class Format < Service
+    # Email Format
+    #
+    # Returns the email format used by a given domain (e.g., first.last, first_last).
+    #
+    # @see https://docs.tomba.io/api/format#email-format
+    # @param domain [String] the domain name to look up the email format for
+    # @return [Hash] API response containing the email format
+    # @raise [Tomba::Exception]
+    def email_format(domain)
+      raise Tomba::Exception, 'Missing required parameter: "domain"' if domain.nil?
+
+      path = '/email-format'
+
+      params = { domain: domain }
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end

data/lib/tomba/services/keys.rb

@@ -1,59 +1,100 @@
-module Tomba
-    class Keys < Service
-
-        def get_keys()
-            path = '/keys/{id}'
-
-            params = {}
-
-            return @client.call('get', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-        def delete_key(id:)
-            if id.nil?
-                raise Tomba::Exception.new('Missing required parameter: "id"')
-            end
-
-            path = '/keys/{id}'
-                .gsub('{id}', id)
-
-            params = {}
-
-            return @client.call('delete', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-        def create_key()
-            path = '/keys/{id}'
+# frozen_string_literal: true
 
-            params = {}
-
-            return @client.call('post', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-        def reset_key(id:)
-            if id.nil?
-                raise Tomba::Exception.new('Missing required parameter: "id"')
-            end
-
-            path = '/keys/{id}'
-                .gsub('{id}', id)
-
-            params = {}
-
-            return @client.call('put', path, {
-                'content-type' => 'application/json',
-            }, params);
-        end
-
-
-        protected
-
-        private
-    end 
-end
+module Tomba
+  # Keys service for managing API keys.
+  #
+  # Provides methods to list, create, reset, and delete API keys.
+  #
+  # @see https://docs.tomba.io/api/keys
+  class Keys < Service
+    # List all API keys.
+    #
+    # Returns all API keys associated with the account.
+    #
+    # @see https://docs.tomba.io/api/keys
+    # @return [Hash] API response containing the list of keys
+    # @raise [Tomba::Exception]
+    def get_keys
+      path = '/keys'
+
+      params = {}
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Get a specific API key by ID.
+    #
+    # @see https://docs.tomba.io/api/keys#get-key
+    # @param id [String] the key ID
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def get_key(id:)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/keys/#{id}"
+
+      @client.call('get', path, {
+                     'content-type' => 'application/json'
+                   }, {})
+    end
+
+    # Delete an API key.
+    #
+    # Removes a specific API key by its ID.
+    #
+    # @see https://docs.tomba.io/api/keys#delete-an-api-key
+    # @param id [String] the key ID to delete
+    # @return [Hash] API response
+    # @raise [Tomba::Exception]
+    def delete_key(id:)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/keys/#{id}"
+
+      params = {}
+
+      @client.call('delete', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Create a new API key.
+    #
+    # Generates a new API key for the account.
+    #
+    # @see https://docs.tomba.io/api/keys#create-an-api-key
+    # @return [Hash] API response containing the new key
+    # @raise [Tomba::Exception]
+    def create_key
+      path = '/keys'
+
+      params = {}
+
+      @client.call('post', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+
+    # Reset an API key.
+    #
+    # Regenerates a specific API key by its ID.
+    #
+    # @see https://docs.tomba.io/api/keys#reset-an-api-key
+    # @param id [String] the key ID to reset
+    # @return [Hash] API response containing the reset key
+    # @raise [Tomba::Exception]
+    def reset_key(id:)
+      raise Tomba::Exception, 'Missing required parameter: "id"' if id.nil?
+
+      path = "/keys/#{id}"
+
+      params = {}
+
+      @client.call('put', path, {
+                     'content-type' => 'application/json'
+                   }, params)
+    end
+  end
+end