data-com-api 0.0.1 → 0.1.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MGVlNTI1Mzg4ZTM5MGRlNTBmNTk2ODhmN2FkYWVjZmYxZTVlYzI5NQ==
+    ZmJiODI5NjlmY2YxNTllZWYxMTM1NDZjYTA1MTI4ZTg5YWNkYTYxYQ==
   data.tar.gz: !binary |-
-    ZDE2NTc1MDg4YzgxNzY1MzhmNWUwZTlhNDEwYmFhYzY0N2QzZDFmYQ==
+    ZWU3YzRiZDY4NjRlMTJiMDMzNDMyZmZjOGNkYmI5ZWM1OWU5NWU0NA==
 SHA512:
   metadata.gz: !binary |-
-    NGVlZGNlMDk0NzAwZDY0MzIxNjQ1MjNkYzJkYzQ3MzU2Mjg1ODk4ZjU4M2Yy
-    NTliZmFhM2Y3ODBkOThlZTZlMTA1MzViMzk5ZTJiNDNjMGZiYjVkYzE0MmU3
-    NmQxMGJlNGE0NjBjMDFkMmQ4ZDRjNDA5ODk5NjFmYjhiOGM5MGE=
+    YjQ0OWJkMWU0ZDA4MGMzMWNlNTBjOTE0ZjYwMDI1MjQ2NjYzODg2OGRjNTg0
+    MzAyZmI3MjVjN2VjMjk1YTQ5NWRiZDM4ZDNiYzQ3MDM3Y2JhYzliMjhjYjAx
+    NWEyN2Y4OTg1Y2I1YTdiZTI3OWRiYTU3NmNhN2FhY2NmNjExZjI=
   data.tar.gz: !binary |-
-    ZWVmMjkwYTMxMjc0N2E5NWUwOGM5ZWQ4YjlmMTYxNzcwYTU4Y2Q2YmY0ODkz
-    MzBkZmRmZGQzMGQzZTg5ZDJmNjA1ODFjOWEzY2QzYmUwNTU2ODI4YzI3ODRk
-    ZmI0OTdkMzFjZGFlY2M3N2I2YzFjNGY4ZGE1ODgxNzU2ZmViM2M=
+    MzFmMTM4NjhkNTZhMjQ4M2UyNzhjZjg4NDYyNWZhNTdmYWRmYTZjNTVmNjE0
+    ODkzYjg5MGIyNDY5OTc2YzUzN2ZiZTljY2JiMWVmZTdkOTQ2ZjAzNjk4NjVh
+    ODhhYTMzNzhkMzU4ZWQxNWQ2Mzk5YmM5YjE4NWJiNTc1NGUzZTE=

data/README.md

@@ -1,4 +1,4 @@
-# Data.com API
+# DataComApi
 
 Allows to interface with Data.com API ( Salesforce, ex Jigsaw ).  
 **Work in progress**
@@ -7,7 +7,7 @@ Allows to interface with Data.com API ( Salesforce, ex Jigsaw ).
 
 Add this line to your application's Gemfile:
 
-    gem 'data-com-api'
+    gem 'data-com-api', '~> 0.1.0'
 
 And then execute:
 
@@ -19,7 +19,85 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+First, create a `DataComApi::Client` instance with the following line:
+
+```ruby
+client = DataComApi::Client.new('your-api-token')
+```
+
+You can then configure the client in the following way:
+
+```ruby
+client.page_size = 100 # Value must be between 1 and 100
+```
+
+You can also get the totals API calls performed on the client with:
+
+```ruby
+client.api_calls_count
+```
+
+Then, you can perform one of the following requests:
+
+- `search_contact`
+- `search_company`
+- `company_contact_count`
+- `contacts`
+
+Every method matches the Data.com API call and support the same parameters. All requests are *lazy*,
+which means that the request will be performed only once you actually perform an action on the response, like
+requesting `size`, `all`, `each` and such (keep reading).
+
+### Client methods aka API responses
+#### #search\_contact and #search\_company
+
+The parameters accepted by this method are the keys of the [DataComApi::QueryParameters](https://github.com/Fire-Dragon-DoL/data-com-api/blob/master/lib/data-com-api/query_parameters.rb). Notice that you can use the key specified as `:from` for a more ruby-like
+syntax.
+
+The returned object is a `DataComApi::SearchContact` which is mostly a [DataComApi::SearchBase](https://github.com/Fire-Dragon-DoL/data-com-api/blob/master/lib/data-com-api/responses/search_base.rb) instance with the following main methods:
+- `size` which returns the `totalHits` field from the response
+  (it will perform a request only if none performed)
+- `all` which returns an array containing all records that can be fetched
+  (be careful, can be **memory hungry**). Will handle paging by itself
+- `each` which yields each record that can be obtained with the request, less memory hungry than previous
+  request. Will handle paging by itself
+- `each_with_index` same as previous one but with index
+- `at_offset` which get one page of records (as an array) at specified offset
+
+Every record returned will be a [DataComApi::Contact](https://github.com/Fire-Dragon-DoL/data-com-api/blob/master/lib/data-com-api/contact.rb) or a [DataComApi::Company](https://github.com/Fire-Dragon-DoL/data-com-api/blob/master/lib/data-com-api/company.rb) instance.
+
+#### #company\_contact\_count
+
+The parameters accepted by this method are `company_id` (required) and the second one is [DataComApi::QueryParameters](https://github.com/Fire-Dragon-DoL/data-com-api/blob/master/lib/data-com-api/query_parameters.rb) which is useful only for the `include_graveyard` key
+
+This method allows you to count contacts per company, the response has the following methods:
+- `size` which returns `totalCount` from API response
+- `url` which returns `url` from API response
+- `levels` which returns an array of [DataComApi::CompanyContactCount::Level](https://github.com/Fire-Dragon-DoL/data-com-api/blob/master/lib/data-com-api/company_contact_count/level.rb)
+- `departments` which returns an array of [DataComApi::CompanyContactCount::Departments](https://github.com/Fire-Dragon-DoL/data-com-api/blob/master/lib/data-com-api/company_contact_count/department.rb)
+
+#### #contacts
+
+The parameters accepted by this method are `contact_ids` (an array of `Fixnum`), `username`, `password`
+which are required and the optional `purchase_flag` which defaults to `false`.
+
+**Be careful, this method may purchase records.**  
+This response has the following methods:
+- `size` which returns `totalHits` from API response
+- `used_points` which returns `pointsUsed` from API response
+- `purchased_contacts` which returns `numberOfContactsPurchased` from API response
+- `point_balance` which returns `pointBalance` from API response
+- `contacts` which returns an array of [DataComApi::Contact](https://github.com/Fire-Dragon-DoL/data-com-api/blob/master/lib/data-com-api/contact.rb)
+
+## TODO
+
+- Implement `partner` request
+- Implement `partner_contacts` request
+- Implement `user` request used to purchase points through API
+- Write some tests for `search_company` which is exactly the same as
+  `search_contact`
+- Improve tests organization
+- Test exceptions when performing API requests
 
 ## Contributing
 

data/data-com-api.gemspec

@@ -22,7 +22,9 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency 'httparty', '~> 0.12.0'
+  spec.add_dependency 'httparty',      '~> 0.12'
+  spec.add_dependency 'activesupport', '~> 4.0'
+  spec.add_dependency 'hashie',        '~> 2.0'
 
   spec.add_development_dependency 'rspec',              '~> 2.14'
   spec.add_development_dependency 'rspec-mocks',        '~> 2.14'

data/lib/data-com-api/api_uri.rb

@@ -0,0 +1,40 @@
+require 'singleton'
+
+module DataComApi
+
+  class BaseApiURI
+    include Singleton
+
+    def company_contact_count(company_id)
+      "/rest/companyContactCount/#{ company_id }.json"
+    end
+
+    def search_contact
+      "/rest/searchContact.json"
+    end
+
+    def search_company
+      "/rest/searchCompany.json"
+    end
+
+    def contacts(contact_ids)
+      "/rest/contacts/#{ contact_ids.join(',') }.json"
+    end
+
+    def partner_contacts(contact_ids)
+      "/rest/partnerContacts/#{ contact_ids.join(',') }.json"
+    end
+
+    def partner
+      "/rest/partner.json"
+    end
+
+    def user
+      "/rest/user.json"
+    end
+    
+  end
+
+  ApiURI = BaseApiURI.instance
+
+end

data/lib/data-com-api/client.rb

@@ -1,4 +1,251 @@
+require 'httparty'
+require 'json'
+require 'data-com-api/errors'
+require 'data-com-api/api_uri'
+require 'data-com-api/responses/search_contact'
+require 'data-com-api/responses/search_company'
+require 'data-com-api/responses/company_contact_count'
+require 'data-com-api/responses/contacts'
+
 module DataComApi
+
   class Client
+    include HTTParty
+    base_uri 'https://www.jigsaw.com'
+
+    ENV_NAME_TOKEN      = 'DATA_COM_TOKEN'.freeze
+    TIME_ZONE           = 'Pacific Time (US & Canada)'.freeze
+    BASE_OFFSET         = 0
+    BASE_PAGE_SIZE      = 50
+    SIZE_ONLY_PAGE_SIZE = 0
+    # We start at 1, 0 is a special case
+    MIN_PAGE_SIZE       = 1
+    MAX_PAGE_SIZE       = 100
+    MAX_OFFSET          = 100_000
+
+    attr_reader :api_calls_count
+    attr_reader :token
+
+    def max_offset
+      MAX_OFFSET
+    end
+
+    def size_only_page_size
+      SIZE_ONLY_PAGE_SIZE
+    end
+
+    def initialize(api_token=nil)
+      @token           = api_token || ENV[ENV_NAME_TOKEN]
+      @page_size       = BASE_PAGE_SIZE
+      @api_calls_count = 0
+
+      raise TokenFailError, 'No token set!' unless @token
+    end
+
+    def page_size
+      @page_size
+    end
+
+    # Page size = 0 returns objects count only (small request)
+    def page_size=(value)
+      real_value = value.to_i
+
+      if real_value < MIN_PAGE_SIZE || real_value > MAX_PAGE_SIZE
+        raise ParamError, <<-eos
+          page_size must be between #{ MIN_PAGE_SIZE } and #{ MAX_PAGE_SIZE },
+          received #{ real_value }"
+        eos
+      end
+
+      @page_size = real_value
+    end
+
+    def search_contact(options={})
+      Responses::SearchContact.new(self, options)
+    end
+
+    def company_contact_count(company_id, options={})
+      Responses::CompanyContactCount.new(self, company_id, options)
+    end
+
+    def contacts(contact_ids, username, password, purchase_flag=false)
+      Responses::Contacts.new(
+        self,
+        contact_ids,
+        username,
+        password,
+        purchase_flag
+      )
+    end
+
+    # Raw calls
+
+    def company_contact_count_raw(company_id, include_graveyard)
+      params = QueryParameters.new(
+        token:             token,
+        company_id:        company_id,
+        include_graveyard: include_graveyard
+      )
+
+      response = self.class.get(
+        ApiURI.company_contact_count(company_id),
+        { query: params }
+      )
+      increase_api_calls_count!
+
+      response.body
+    end
+
+    def search_contact_raw(options={})
+      response = self.class.get(
+        ApiURI.search_contact,
+        generate_params(options)
+      )
+      increase_api_calls_count!
+
+      response.body
+    end
+
+    def search_company_raw(options={})
+      response = self.class.get(
+        ApiURI.search_company,
+        generate_params(options)
+      )
+      increase_api_calls_count!
+
+      response.body
+    end
+
+    def contacts_raw(contact_ids, username, password, purchase_flag=false)
+      raise ParamError, 'One contact required at least' unless contact_ids.size > 0
+
+      params = QueryParameters.new(
+        token:         token,
+        username:      username,
+        password:      password,
+        purchase_flag: purchase_flag
+      )
+      
+      response = self.class.get(
+        ApiURI.contacts(contact_ids),
+        { query: params }
+      )
+      increase_api_calls_count!
+
+      response.body
+    end
+
+    def partner_contacts_raw(contact_ids, end_org_id, end_user_id)
+      raise ParamError, 'One contact required at least' unless contact_ids.size > 0
+
+      params = QueryParameters.new(
+        token:       token,
+        end_org_id:  end_org_id,
+        end_user_id: end_user_id
+      )
+      
+      response = self.class.get(
+        ApiURI.partner_contacts(contact_ids),
+        { query: params }
+      )
+      increase_api_calls_count!
+
+      response.body
+    end
+
+    def partner_raw
+      params = QueryParameters.new(token: token)
+      
+      response = self.class.get(
+        ApiURI.partner,
+        { query: params }
+      )
+      increase_api_calls_count!
+
+      response.body
+    end
+
+    def user_raw(username, password)
+      params = QueryParameters.new(
+        username: username,
+        password: password,
+        token:    token
+      )
+      
+      response = self.class.get(
+        ApiURI.user,
+        { query: params }
+      )
+      increase_api_calls_count!
+
+      response.body
+    end
+
+    # JSON calls
+
+    def company_contact_count_raw_json(company_id, include_graveyard)
+      json_or_raise company_contact_count_raw(company_id, include_graveyard)
+    end
+
+    def search_contact_raw_json(options={})
+      json_or_raise search_contact_raw(options)
+    end
+
+    def search_company_raw_json(options={})
+      json_or_raise search_company_raw(options)
+    end
+
+    def contacts_raw_json(contact_ids, username, password, purchase_flag=false)
+      json_or_raise contacts_raw(
+        contact_ids,
+        username,
+        password,
+        purchase_flag
+      )
+    end
+
+    def partner_contacts_raw_json(contact_ids, end_org_id, end_user_id)
+      json_or_raise partner_contacts_raw(
+        contact_ids,
+        end_org_id,
+        end_user_id
+      )
+    end
+
+    def partner_raw_json
+      json_or_raise partner_raw
+    end
+
+    def user_raw_json(username, password)
+      json_or_raise user_raw(username, password)
+    end
+
+    private
+
+      def json_or_raise(json_str)
+        json = JSON.parse(json_str)
+
+        if json.kind_of? Array
+          error = json.first
+          raise Error.from_code(error['errorCode']).new(error['errorMsg'])
+        end
+
+        json
+      end
+
+      def generate_params(options)
+        params           = QueryParameters.new(options)
+        params.offset    = BASE_OFFSET unless params.offset
+        params.page_size = page_size   unless params.pageSize
+        params.token     = token
+
+        { query: params }
+      end
+
+      def increase_api_calls_count!
+        @api_calls_count += 1
+      end
+
   end
+
 end

data/lib/data-com-api/company.rb

@@ -0,0 +1,17 @@
+require 'hashie'
+
+module DataComApi
+  class Company < Hashie::Trash
+    property :id,              from: :companyId
+    property :zip
+    property :address
+    property :name
+    property :active_contacts, from: :activeContacts
+    property :state
+    property :graveyarded
+    property :city
+    property :country
+
+    alias_method :graveyarded?, :graveyarded
+  end
+end

data/lib/data-com-api/company_contact_count/department.rb

@@ -0,0 +1,17 @@
+require 'hashie'
+
+module DataComApi
+
+  module CompanyContactCount
+
+    class Department < Hashie::Trash
+      property :count
+      property :name
+      property :url
+
+      alias_method :size, :count
+    end
+
+  end
+
+end

data/lib/data-com-api/company_contact_count/level.rb

@@ -0,0 +1,17 @@
+require 'hashie'
+
+module DataComApi
+
+  module CompanyContactCount
+
+    class Level < Hashie::Trash
+      property :count
+      property :name
+      property :url
+
+      alias_method :size, :count
+    end
+
+  end
+
+end

data/lib/data-com-api/contact.rb

@@ -0,0 +1,32 @@
+require 'hashie'
+require 'active_support/time'
+
+module DataComApi
+  class Contact < Hashie::Trash
+    property :id,               from: :contactId
+    property :zip
+    property :phone
+    property :area_code,        from: :areaCode
+    property :updated_at,       from: :updatedDate,  with: ->(v) { Time.parse(v.to_s).utc }
+    property :seo_contact_url,  from: :seoContactURL
+    property :state
+    property :first_name,       from: :firstname
+    property :last_name,        from: :lastname
+    property :company_name,     from: :companyName
+    property :contact_url,      from: :contactURL
+    property :contact_sales,    from: :contactSales
+    property :country
+    property :owned
+    property :city
+    property :title
+    property :email
+    property :address
+    property :graveyard_status, from: :graveyardStatus
+    property :owned_type,       from: :ownedType
+    property :company_id,       from: :companyId
+
+    alias_method :graveyarded,  :graveyard_status
+    alias_method :graveyarded?, :graveyarded
+    alias_method :owned?,       :owned
+  end
+end

data/lib/data-com-api/errors.rb

@@ -0,0 +1,96 @@
+require 'active_support/core_ext/hash/reverse_merge'
+
+module DataComApi
+
+  class Error < StandardError
+
+    API_HTTP_STATUS_CODE = 0
+    API_ERROR_CODE       = 'no error code provided'
+
+    attr_reader :http_status_code
+    attr_reader :api_stack_trace
+    attr_reader :error_code
+
+    def initialize(msg=nil, options={})
+      options = options.reverse_merge({
+        http_status_code: nil,
+        api_stack_trace:  nil,
+        error_code:       nil
+      })
+
+      @http_status_code ||= options[:http_status_code] || self.class::API_HTTP_STATUS_CODE
+      @api_stack_trace  ||= options[:api_stack_trace]
+      @error_code       ||= options[:error_code] || self.class::API_ERROR_CODE
+
+      super(msg)
+    end
+
+    def self.from_code(error_code_str)
+      case error_code_str
+      when ParamError::API_ERROR_CODE             then ParamError
+      when LoginFailError::API_ERROR_CODE         then LoginFailError
+      when TokenFailError::API_ERROR_CODE         then TokenFailError
+      when PurchaseLowPointsError::API_ERROR_CODE then PurchaseLowPointsError
+      when ContactNotExistError::API_ERROR_CODE   then ContactNotExistError
+      when ContactNotOwnedError::API_ERROR_CODE   then ContactNotOwnedError
+      when SearchError::API_ERROR_CODE            then SearchError
+      when SysError::API_ERROR_CODE               then SysError
+      when NotImplementedError::API_ERROR_CODE    then NotImplementedError
+      when NotAvailableError::API_ERROR_CODE      then NotAvailableError
+      else Error
+      end
+    end
+
+  end
+
+  class ParamError < Error
+    API_HTTP_STATUS_CODE = 400
+    API_ERROR_CODE       = 'PARAM_ERROR'.freeze
+  end
+
+  class LoginFailError < Error
+    API_HTTP_STATUS_CODE = 403
+    API_ERROR_CODE       = 'LOGIN_FAIL'.freeze
+  end
+
+  class TokenFailError < Error
+    API_HTTP_STATUS_CODE = 403
+    API_ERROR_CODE       = 'TOKEN_FAIL'.freeze
+  end
+
+  class PurchaseLowPointsError < Error
+    API_HTTP_STATUS_CODE = 405
+    API_ERROR_CODE       = 'PURCHASE_LOW_POINTS'.freeze
+  end
+
+  class ContactNotExistError < Error
+    API_HTTP_STATUS_CODE = 404
+    API_ERROR_CODE       = 'CONTACT_NOT_EXIST'.freeze
+  end
+
+  class ContactNotOwnedError < Error
+    API_HTTP_STATUS_CODE = 405
+    API_ERROR_CODE       = 'CONTACT_NOT_OWNED'.freeze
+  end
+
+  class SearchError < Error
+    API_HTTP_STATUS_CODE = 500
+    API_ERROR_CODE       = 'SEARCH_ERROR'.freeze
+  end
+
+  class SysError < Error
+    API_HTTP_STATUS_CODE = 500
+    API_ERROR_CODE       = 'SYS_ERROR'.freeze
+  end
+
+  class NotImplementedError < Error
+    API_HTTP_STATUS_CODE = 501
+    API_ERROR_CODE       = 'NOT_IMPLEMENTED'.freeze
+  end
+
+  class NotAvailableError < Error
+    API_HTTP_STATUS_CODE = 503
+    API_ERROR_CODE       = 'NOT_AVAILABLE'.freeze
+  end
+
+end

data/lib/data-com-api/query_parameters.rb

@@ -0,0 +1,66 @@
+require 'hashie'
+require 'active_support/time'
+
+module DataComApi
+  class QueryParameters < Hashie::Trash
+    UNALLOWED_FIELDS = [
+      :offset,
+      :pageSize,
+      :page_size,
+      :username,
+      :password,
+      :token
+    ].freeze
+
+    property :companyId,        from: :company_id
+    property :updatedSince,     from: :updated_since, with: ->(v) do
+      Time.parse(v).utc.in_time_zone(Client::TIME_ZONE)
+    end
+    property :title
+    property :companyName,      from: :company_name
+    property :name
+    property :lastname
+    property :firstname
+    property :email
+    property :levels
+    property :departments
+    property :country
+    property :state
+    property :metroArea,        from: :metro_area
+    property :areaCode,         from: :area_code
+    property :zipCode,          from: :zip_code
+    property :industry
+    property :subIndustry,      from: :sub_industry
+    property :employees
+    property :revenue
+    property :ownership
+    property :websiteType,      from: :website_type
+    property :fortuneRank,      from: :fortune_rank
+    property :includeGraveyard, from: :include_graveyard
+    property :order
+    property :orderBy,          from: :order_by
+    property :purchaseFlag,     from: :purchase_flag
+    property :endOrgId,         from: :end_org_id
+    property :endUserId,        from: :end_user_id
+
+    # Special params, used to inject into query, set only through gem
+    property :offset
+    property :pageSize,         from: :page_size
+    property :username
+    property :password
+    property :token
+
+    # Destructively convert all values using into strings
+    def self.stringify_hash_values(hash)
+      hash.each_pair do |key, value|
+        hash[key] = value.to_s
+      end
+      hash
+    end
+
+    def to_hash
+      self.class.stringify_hash_values(super)
+    end
+
+  end
+end

data/lib/data-com-api/responses/base.rb

@@ -0,0 +1,19 @@
+require 'active_support/cache'
+
+module DataComApi
+  module Responses
+    class Base
+      
+      def initialize(api_client)
+        @client = api_client
+      end
+
+      protected
+
+        def client
+          @client
+        end
+
+    end
+  end
+end