clearbit 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9bfa4e2e52a22c81346477b50bbd5d4152abf27a
-  data.tar.gz: 0ddaa5a863838daf609679587149fdc32ee9af40
+SHA256:
+  metadata.gz: 7e0b00b7a895da02d3d5ca094f8960a954b5ecde28891979a515015608c2fd6d
+  data.tar.gz: e4e411ccc729b972cf7139594e59da959ff22222f82fb53e312c1b529512e7ee
 SHA512:
-  metadata.gz: 2f1a861b55adb44a91ac887d53099166336e3373ffe48d945806c5d83f86f091b2fc8e0f6cb123160b2f09e6580377fd2dd92353d79c2338aa957f6269e7a1c7
-  data.tar.gz: bfa3ffd82393968ae7e736d2e4bcee05acbb18b0a17413fcd6262aff1810f80187ba3c9df0585ce720aa9fc11f184ec441336ee04cede5f9a5aa72cbd6f0f510
+  metadata.gz: 368ac6459e7e2613e2636731fef9db010d3ae30c9772b7d57017c24d96b4760c9a1af6cddfcfbe6b793051e07552194c519d4a201883f04ec861185b8d5e475a
+  data.tar.gz: '08f475f7c73ccd1c77dd5b660f9c061bc1531402e1d982cf8f2142d5094fe7354087da8a27f50ed30e9562feb29c67b607495e7399d366e1d480b1915f150efa'

data/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+* @bentona
+* @jcutrell
+

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 Clearbit.
+Copyright (c) 2018 Clearbit.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -35,9 +35,36 @@ person  = result.person
 company = result.company
 ```
 
-Passing the `stream` option makes the operation blocking - it could hang for 4-5 seconds if we haven't seen the email before. Alternatively you can use our [webhook](https://clearbit.com/docs#webhooks) API. If a person or company can't be found, then they'll be `nil`.
+Passing the `stream` option makes the operation blocking - it could hang for 4-5 seconds if we haven't seen the email before. Alternatively you can use our [webhook](https://clearbit.com/docs#webhooks) API.
+
+Without the `stream` option, the operation is non-blocking, and we will immediately return either the enriched data or `Clearbit::Pending` object.
+
+```ruby
+result = Clearbit::Enrichment.find(email: 'alex@alexmaccaw.com')
+
+if result.pending?
+  # Lookup queued - try again later
+end
+
+# Later
+unless result.pending?
+  person  = result.person
+  company = result.company
+end
+
+```
+
+In either case, if a person or company can't be found, the result will be `nil`.
 
 See the [documentation](https://clearbit.com/docs#person-api) for more information.
+## Name to Domain
+
+To find the domain based on the name of a resource, you can use the `NameDomain` API.
+
+```ruby
+name = Clearbit::NameDomain.find(name: 'Uber')
+```
+For more information look at the [documentation](https://dashboard.clearbit.com/docs?ruby#name-to-domain-api).
 
 ## Company lookup
 
@@ -51,6 +78,22 @@ If the company can't be found, then `nil` will be returned.
 
 See the [documentation](https://clearbit.com/docs#company-api) for more information.
 
+## Analytics
+
+Identify users by sending their `user_id`, and adding details like their `email` and `company_domain` to create People and Companies inside of Clearbit X.
+
+```ruby
+Clearbit::Analytics.identify(
+  user_id: '1234', # Required
+  traits: {
+    email: 'david@clearbitexample.com', # Optional, but strongly recommended
+    company_domain: 'clearbit.com',     # Optional, but strongly recommended
+    first_name: 'David', # Optional
+    last_name: 'Lumley', # Optional
+  },
+)
+```
+
 ## Other APIs
 
 For more info on our other APIs (such as the Watchlist or Discover APIs), please see our [main documentation](https://clearbit.com/docs).
@@ -62,7 +105,7 @@ For rack apps use the `Clearbit::Webhook` module to wrap deserialization and ver
 ``` ruby
 post '/v1/webhooks/clearbit' do
   begin
-    webhook = Clearbit::Webhook.new(env)
+    webhook = Clearbit::Webhook.new(request.env)
     webhook.type #=> 'person'
     webhook.body.name.given_name #=> 'Alex'
 
@@ -76,5 +119,16 @@ end
 The global Clearbit.key can be overriden for multi-tenant apps using multiple Clearbit keys like so:
 
 ```ruby
-webhook = Clearbit::Webhook.new(env, 'CLEARBIT_KEY')
+webhook = Clearbit::Webhook.new(request.env, 'CLEARBIT_KEY')
+```
+
+## Proxy Support
+
+Passing the proxy option allows you to specify a proxy server to pass the request through.
+
+``` ruby
+company = Clearbit::Enrichment::Company.find(
+  domain: 'uber.com',
+  proxy: 'https://user:password@proxyserver.tld:8080'
+)
 ```

data/clearbit.gemspec

@@ -18,6 +18,8 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
+  spec.add_dependency 'json', ['~> 1.7'] if RUBY_VERSION < '1.9'
+
   spec.add_development_dependency 'bundler', '~> 1.3'
   spec.add_development_dependency 'net-http-spy'
   spec.add_development_dependency 'pry'

data/examples/prospector.rb

@@ -1,8 +1,9 @@
 require 'clearbit'
-require 'pp'
 
-people = Clearbit::Prospector.search(domain: 'clearbit.com')
+response = Clearbit::Prospector.search(domain: 'clearbit.com', page: 1)
 
-people.each do |person|
-  puts [person.name.full_name, person.email]
+puts "Displaying #{response[:results].size} of #{response[:total]} results:"
+
+response[:results].each_with_index do |person, index|
+  puts "  #{index + 1}. #{person.name.full_name} (#{person.email})"
 end

data/lib/clearbit.rb

@@ -1,5 +1,6 @@
 require 'nestful'
 require 'clearbit/version'
+require 'clearbit/analytics'
 
 module Clearbit
   def self.api_key=(value)
@@ -18,6 +19,7 @@ module Clearbit
     key || raise('Clearbit.key not set')
   end
 
+  autoload :Audiences, 'clearbit/audiences'
   autoload :Autocomplete, 'clearbit/autocomplete'
   autoload :Base, 'clearbit/base'
   autoload :Discovery, 'clearbit/discovery'

data/lib/clearbit/analytics.rb

@@ -0,0 +1,46 @@
+require 'clearbit/analytics/defaults'
+require 'clearbit/analytics/utils'
+require 'clearbit/analytics/field_parser'
+require 'clearbit/analytics/client'
+require 'clearbit/analytics/worker'
+require 'clearbit/analytics/request'
+require 'clearbit/analytics/response'
+require 'clearbit/analytics/logging'
+
+module Clearbit
+  class Analytics
+    # Proxy identify through to a client instance, in order to keep the client
+    # consistent with how the other Clearbit APIs are accessed
+    def self.identify(args)
+      analytics = new(write_key: Clearbit.key)
+      analytics.identify(args)
+      analytics.flush
+    end
+
+    # Initializes a new instance of {Clearbit::Analytics::Client}, to which all
+    # method calls are proxied.
+    #
+    # @param options includes options that are passed down to
+    #   {Clearbit::Analytics::Client#initialize}
+    # @option options [Boolean] :stub (false) If true, requests don't hit the
+    #   server and are stubbed to be successful.
+    def initialize(options = {})
+      Request.stub = options[:stub] if options.has_key?(:stub)
+      @client = Clearbit::Analytics::Client.new options
+    end
+
+    def method_missing(message, *args, &block)
+      if @client.respond_to? message
+        @client.send message, *args, &block
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @client.respond_to?(method_name) || super
+    end
+
+    include Logging
+  end
+end

data/lib/clearbit/analytics/LICENSE

@@ -0,0 +1,10 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Segment Inc. <friends@segment.com>
+Copyright (c) 2019 Clearbit. <support@clearbit.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/clearbit/analytics/backoff_policy.rb

@@ -0,0 +1,49 @@
+require 'clearbit/analytics/defaults'
+
+module Clearbit
+  class Analytics
+    class BackoffPolicy
+      include Clearbit::Analytics::Defaults::BackoffPolicy
+
+      # @param [Hash] opts
+      # @option opts [Numeric] :min_timeout_ms The minimum backoff timeout
+      # @option opts [Numeric] :max_timeout_ms The maximum backoff timeout
+      # @option opts [Numeric] :multiplier The value to multiply the current
+      #   interval with for each retry attempt
+      # @option opts [Numeric] :randomization_factor The randomization factor
+      #   to use to create a range around the retry interval
+      def initialize(opts = {})
+        @min_timeout_ms = opts[:min_timeout_ms] || MIN_TIMEOUT_MS
+        @max_timeout_ms = opts[:max_timeout_ms] || MAX_TIMEOUT_MS
+        @multiplier = opts[:multiplier] || MULTIPLIER
+        @randomization_factor = opts[:randomization_factor] || RANDOMIZATION_FACTOR
+
+        @attempts = 0
+      end
+
+      # @return [Numeric] the next backoff interval, in milliseconds.
+      def next_interval
+        interval = @min_timeout_ms * (@multiplier**@attempts)
+        interval = add_jitter(interval, @randomization_factor)
+
+        @attempts += 1
+
+        [interval, @max_timeout_ms].min
+      end
+
+      private
+
+      def add_jitter(base, randomization_factor)
+        random_number = rand
+        max_deviation = base * randomization_factor
+        deviation = random_number * max_deviation
+
+        if random_number < 0.5
+          base - deviation
+        else
+          base + deviation
+        end
+      end
+    end
+  end
+end

data/lib/clearbit/analytics/client.rb

@@ -0,0 +1,189 @@
+require 'thread'
+require 'time'
+
+require 'clearbit/analytics/defaults'
+require 'clearbit/analytics/logging'
+require 'clearbit/analytics/utils'
+require 'clearbit/analytics/worker'
+
+module Clearbit
+  class Analytics
+    class Client
+      include Clearbit::Analytics::Utils
+      include Clearbit::Analytics::Logging
+
+      # @param [Hash] opts
+      # @option opts [String] :write_key Your project's write_key
+      # @option opts [FixNum] :max_queue_size Maximum number of calls to be
+      #   remain queued.
+      # @option opts [Proc] :on_error Handles error calls from the API.
+      def initialize(opts = {})
+        symbolize_keys!(opts)
+
+        @queue = Queue.new
+        @write_key = opts[:write_key]
+        @max_queue_size = opts[:max_queue_size] || Defaults::Queue::MAX_SIZE
+        @worker_mutex = Mutex.new
+        @worker = Worker.new(@queue, @write_key, opts)
+
+        check_write_key!
+
+        at_exit { @worker_thread && @worker_thread[:should_exit] = true }
+      end
+
+      # Synchronously waits until the worker has flushed the queue.
+      #
+      # Use only for scripts which are not long-running, and will specifically
+      # exit
+      def flush
+        while !@queue.empty? || @worker.is_requesting?
+          ensure_worker_running
+          sleep(0.1)
+        end
+      end
+
+      # @!macro common_attrs
+      #   @option attrs [String] :anonymous_id ID for a user when you don't know
+      #     who they are yet. (optional but you must provide either an
+      #     `anonymous_id` or `user_id`)
+      #   @option attrs [Hash] :context ({})
+      #   @option attrs [Hash] :integrations What integrations this event
+      #     goes to (optional)
+      #   @option attrs [String] :message_id ID that uniquely
+      #     identifies a message across the API. (optional)
+      #   @option attrs [Time] :timestamp When the event occurred (optional)
+      #   @option attrs [String] :user_id The ID for this user in your database
+      #     (optional but you must provide either an `anonymous_id` or `user_id`)
+      #   @option attrs [Hash] :options Options such as user traits (optional)
+
+      # Tracks an event
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#track
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :event Event name
+      # @option attrs [Hash] :properties Event properties (optional)
+      # @macro common_attrs
+      def track(attrs)
+        symbolize_keys! attrs
+        enqueue(FieldParser.parse_for_track(attrs))
+      end
+
+      # Identifies a user
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#identify
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [Hash] :traits User traits (optional)
+      # @macro common_attrs
+      def identify(attrs)
+        symbolize_keys! attrs
+        enqueue(FieldParser.parse_for_identify(attrs))
+      end
+
+      # Aliases a user from one id to another
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#alias
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :previous_id The ID to alias from
+      # @macro common_attrs
+      def alias(attrs)
+        symbolize_keys! attrs
+        enqueue(FieldParser.parse_for_alias(attrs))
+      end
+
+      # Associates a user identity with a group.
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#group
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :group_id The ID of the group
+      # @option attrs [Hash] :traits User traits (optional)
+      # @macro common_attrs
+      def group(attrs)
+        symbolize_keys! attrs
+        enqueue(FieldParser.parse_for_group(attrs))
+      end
+
+      # Records a page view
+      #
+      # @see https://segment.com/docs/sources/server/ruby/#page
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :name Name of the page
+      # @option attrs [Hash] :properties Page properties (optional)
+      # @macro common_attrs
+      def page(attrs)
+        symbolize_keys! attrs
+        enqueue(FieldParser.parse_for_page(attrs))
+      end
+
+      # Records a screen view (for a mobile app)
+      #
+      # @param [Hash] attrs
+      #
+      # @option attrs [String] :name Name of the screen
+      # @option attrs [Hash] :properties Screen properties (optional)
+      # @option attrs [String] :category The screen category (optional)
+      # @macro common_attrs
+      def screen(attrs)
+        symbolize_keys! attrs
+        enqueue(FieldParser.parse_for_screen(attrs))
+      end
+
+      # @return [Fixnum] number of messages in the queue
+      def queued_messages
+        @queue.length
+      end
+
+      private
+
+      # private: Enqueues the action.
+      #
+      # returns Boolean of whether the item was added to the queue.
+      def enqueue(action)
+        # add our request id for tracing purposes
+        action[:messageId] ||= uid
+
+        if @queue.length < @max_queue_size
+          @queue << action
+          ensure_worker_running
+
+          true
+        else
+          logger.warn(
+            'Queue is full, dropping events. The :max_queue_size ' \
+            'configuration parameter can be increased to prevent this from ' \
+            'happening.'
+          )
+          false
+        end
+      end
+
+      # private: Checks that the write_key is properly initialized
+      def check_write_key!
+        raise ArgumentError, 'Write key must be initialized' if @write_key.nil?
+      end
+
+      def ensure_worker_running
+        return if worker_running?
+        @worker_mutex.synchronize do
+          return if worker_running?
+          @worker_thread = Thread.new do
+            @worker.run
+          end
+        end
+      end
+
+      def worker_running?
+        @worker_thread && @worker_thread.alive?
+      end
+    end
+  end
+end

data/lib/clearbit/analytics/defaults.rb

@@ -0,0 +1,36 @@
+module Clearbit
+  class Analytics
+    module Defaults
+      module Request
+        HOST = 'x.clearbit.com'
+        PORT = 443
+        PATH = '/v1/import'
+        SSL = true
+        HEADERS = { 'Accept' => 'application/json',
+                    'Content-Type' => 'application/json',
+                    'User-Agent' => "clearbit-ruby/#{Clearbit::VERSION}" }
+        RETRIES = 10
+      end
+
+      module Queue
+        MAX_SIZE = 10000
+      end
+
+      module Message
+        MAX_BYTES = 32768 # 32Kb
+      end
+
+      module MessageBatch
+        MAX_BYTES = 512_000 # 500Kb
+        MAX_SIZE = 100
+      end
+
+      module BackoffPolicy
+        MIN_TIMEOUT_MS = 100
+        MAX_TIMEOUT_MS = 10000
+        MULTIPLIER = 1.5
+        RANDOMIZATION_FACTOR = 0.5
+      end
+    end
+  end
+end

data/lib/clearbit/analytics/field_parser.rb

@@ -0,0 +1,192 @@
+module Clearbit
+  class Analytics
+    # Handles parsing fields according to the Segment Spec
+    #
+    # @see https://segment.com/docs/spec/
+    class FieldParser
+      class << self
+        include Clearbit::Analytics::Utils
+
+        # In addition to the common fields, track accepts:
+        #
+        # - "event"
+        # - "properties"
+        def parse_for_track(fields)
+          common = parse_common_fields(fields)
+
+          event = fields[:event]
+          properties = fields[:properties] || {}
+
+          check_presence!(event, 'event')
+          check_is_hash!(properties, 'properties')
+
+          isoify_dates! properties
+
+          common.merge({
+            :type => 'track',
+            :event => event.to_s,
+            :properties => properties
+          })
+        end
+
+        # In addition to the common fields, identify accepts:
+        #
+        # - "traits"
+        def parse_for_identify(fields)
+          common = parse_common_fields(fields)
+
+          traits = fields[:traits] || {}
+          check_is_hash!(traits, 'traits')
+          isoify_dates! traits
+
+          common.merge({
+            :type => 'identify',
+            :traits => traits
+          })
+        end
+
+        # In addition to the common fields, alias accepts:
+        #
+        # - "previous_id"
+        def parse_for_alias(fields)
+          common = parse_common_fields(fields)
+
+          previous_id = fields[:previous_id]
+          check_presence!(previous_id, 'previous_id')
+
+          common.merge({
+            :type => 'alias',
+            :previousId => previous_id
+          })
+        end
+
+        # In addition to the common fields, group accepts:
+        #
+        # - "group_id"
+        # - "traits"
+        def parse_for_group(fields)
+          common = parse_common_fields(fields)
+
+          group_id = fields[:group_id]
+          traits = fields[:traits] || {}
+
+          check_presence!(group_id, 'group_id')
+          check_is_hash!(traits, 'traits')
+
+          isoify_dates! traits
+
+          common.merge({
+            :type => 'group',
+            :groupId => group_id,
+            :traits => traits
+          })
+        end
+
+        # In addition to the common fields, page accepts:
+        #
+        # - "name"
+        # - "properties"
+        def parse_for_page(fields)
+          common = parse_common_fields(fields)
+
+          name = fields[:name] || ''
+          properties = fields[:properties] || {}
+
+          check_is_hash!(properties, 'properties')
+
+          isoify_dates! properties
+
+          common.merge({
+            :type => 'page',
+            :name => name.to_s,
+            :properties => properties
+          })
+        end
+
+        # In addition to the common fields, screen accepts:
+        #
+        # - "name"
+        # - "properties"
+        # - "category" (Not in spec, retained for backward compatibility"
+        def parse_for_screen(fields)
+          common = parse_common_fields(fields)
+
+          name = fields[:name]
+          properties = fields[:properties] || {}
+          category = fields[:category]
+
+          check_presence!(name, 'name')
+          check_is_hash!(properties, 'properties')
+
+          isoify_dates! properties
+
+          parsed = common.merge({
+            :type => 'screen',
+            :name => name,
+            :properties => properties
+          })
+
+          parsed[:category] = category if category
+
+          parsed
+        end
+
+        private
+
+        def parse_common_fields(fields)
+          timestamp = fields[:timestamp] || Time.new
+          message_id = fields[:message_id].to_s if fields[:message_id]
+          context = fields[:context] || {}
+
+          check_user_id! fields
+          check_timestamp! timestamp
+
+          add_context! context
+
+          parsed = {
+            :context => context,
+            :messageId => message_id,
+            :timestamp => datetime_in_iso8601(timestamp)
+          }
+
+          parsed[:userId] = fields[:user_id] if fields[:user_id]
+          parsed[:anonymousId] = fields[:anonymous_id] if fields[:anonymous_id]
+          parsed[:integrations] = fields[:integrations] if fields[:integrations]
+
+          # Not in spec, retained for backward compatibility
+          parsed[:options] = fields[:options] if fields[:options]
+
+          parsed
+        end
+
+        def check_user_id!(fields)
+          unless fields[:user_id] || fields[:anonymous_id]
+            raise ArgumentError, 'Must supply either user_id or anonymous_id'
+          end
+        end
+
+        def check_timestamp!(timestamp)
+          raise ArgumentError, 'Timestamp must be a Time' unless timestamp.is_a? Time
+        end
+
+        def add_context!(context)
+          context[:library] = { :name => 'analytics-ruby', :version => Clearbit::VERSION.to_s }
+        end
+
+        # private: Ensures that a string is non-empty
+        #
+        # obj    - String|Number that must be non-blank
+        # name   - Name of the validated value
+        def check_presence!(obj, name)
+          if obj.nil? || (obj.is_a?(String) && obj.empty?)
+            raise ArgumentError, "#{name} must be given"
+          end
+        end
+
+        def check_is_hash!(obj, name)
+          raise ArgumentError, "#{name} must be a Hash" unless obj.is_a? Hash
+        end
+      end
+    end
+  end
+end

data/lib/clearbit/analytics/logging.rb

@@ -0,0 +1,60 @@
+require 'logger'
+
+module Clearbit
+  class Analytics
+    # Wraps an existing logger and adds a prefix to all messages
+    class PrefixedLogger
+      def initialize(logger, prefix)
+        @logger = logger
+        @prefix = prefix
+      end
+
+      def debug(msg)
+        @logger.debug("#{@prefix} #{msg}")
+      end
+
+      def info(msg)
+        @logger.info("#{@prefix} #{msg}")
+      end
+
+      def warn(msg)
+        @logger.warn("#{@prefix} #{msg}")
+      end
+
+      def error(msg)
+        @logger.error("#{@prefix} #{msg}")
+      end
+    end
+
+    module Logging
+      class << self
+        def logger
+          return @logger if @logger
+
+          base_logger = if defined?(Rails)
+                          Rails.logger
+                        else
+                          logger = Logger.new STDOUT
+                          logger.progname = 'Clearbit::Analytics'
+                          logger
+                        end
+          @logger = PrefixedLogger.new(base_logger, '[analytics-ruby]')
+        end
+
+        attr_writer :logger
+      end
+
+      def self.included(base)
+        class << base
+          def logger
+            Logging.logger
+          end
+        end
+      end
+
+      def logger
+        Logging.logger
+      end
+    end
+  end
+end

data/lib/clearbit/analytics/message_batch.rb

@@ -0,0 +1,72 @@
+require 'forwardable'
+require 'clearbit/analytics/logging'
+
+module Clearbit
+  class Analytics
+    # A batch of `Message`s to be sent to the API
+    class MessageBatch
+      class JSONGenerationError < StandardError; end
+
+      extend Forwardable
+      include Clearbit::Analytics::Logging
+      include Clearbit::Analytics::Defaults::MessageBatch
+
+      def initialize(max_message_count)
+        @messages = []
+        @max_message_count = max_message_count
+        @json_size = 0
+      end
+
+      def <<(message)
+        begin
+          message_json = message.to_json
+        rescue StandardError => e
+          raise JSONGenerationError, "Serialization error: #{e}"
+        end
+
+        message_json_size = message_json.bytesize
+        if message_too_big?(message_json_size)
+          logger.error('a message exceeded the maximum allowed size')
+        else
+          @messages << message
+          @json_size += message_json_size + 1 # One byte for the comma
+        end
+      end
+
+      def full?
+        item_count_exhausted? || size_exhausted?
+      end
+
+      def clear
+        @messages.clear
+        @json_size = 0
+      end
+
+      def_delegators :@messages, :to_json
+      def_delegators :@messages, :empty?
+      def_delegators :@messages, :length
+
+      private
+
+      def item_count_exhausted?
+        @messages.length >= @max_message_count
+      end
+
+      def message_too_big?(message_json_size)
+        message_json_size > Defaults::Message::MAX_BYTES
+      end
+
+      # We consider the max size here as just enough to leave room for one more
+      # message of the largest size possible. This is a shortcut that allows us
+      # to use a native Ruby `Queue` that doesn't allow peeking. The tradeoff
+      # here is that we might fit in less messages than possible into a batch.
+      #
+      # The alternative is to use our own `Queue` implementation that allows
+      # peeking, and to consider the next message size when calculating whether
+      # the message can be accomodated in this batch.
+      def size_exhausted?
+        @json_size >= (MAX_BYTES - Defaults::Message::MAX_BYTES)
+      end
+    end
+  end
+end

data/lib/clearbit/analytics/request.rb

@@ -0,0 +1,134 @@
+require 'clearbit/analytics/defaults'
+require 'clearbit/analytics/utils'
+require 'clearbit/analytics/response'
+require 'clearbit/analytics/logging'
+require 'clearbit/analytics/backoff_policy'
+require 'net/http'
+require 'net/https'
+require 'json'
+
+module Clearbit
+  class Analytics
+    class Request
+      include Clearbit::Analytics::Defaults::Request
+      include Clearbit::Analytics::Utils
+      include Clearbit::Analytics::Logging
+
+      # public: Creates a new request object to send analytics batch
+      #
+      def initialize(options = {})
+        options[:host] ||= HOST
+        options[:port] ||= PORT
+        options[:ssl] ||= SSL
+        @headers = options[:headers] || HEADERS
+        @path = options[:path] || PATH
+        @retries = options[:retries] || RETRIES
+        @backoff_policy =
+          options[:backoff_policy] || Clearbit::Analytics::BackoffPolicy.new
+
+        http = Net::HTTP.new(options[:host], options[:port])
+        http.use_ssl = options[:ssl]
+        http.read_timeout = 8
+        http.open_timeout = 4
+
+        @http = http
+      end
+
+      # public: Posts the write key and batch of messages to the API.
+      #
+      # returns - Response of the status and error if it exists
+      def post(write_key, batch)
+        logger.debug("Sending request for #{batch.length} items")
+
+        last_response, exception = retry_with_backoff(@retries) do
+          status_code, body = send_request(write_key, batch)
+          error = JSON.parse(body)['error']
+          should_retry = should_retry_request?(status_code, body)
+          logger.debug("Response status code: #{status_code}")
+          logger.debug("Response error: #{error}") if error
+
+          [Response.new(status_code, error), should_retry]
+        end
+
+        if exception
+          logger.error(exception.message)
+          exception.backtrace.each { |line| logger.error(line) }
+          Response.new(-1, exception.to_s)
+        else
+          last_response
+        end
+      end
+
+      private
+
+      def should_retry_request?(status_code, body)
+        if status_code >= 500
+          true # Server error
+        elsif status_code == 429
+          true # Rate limited
+        elsif status_code >= 400
+          logger.error(body)
+          false # Client error. Do not retry, but log
+        else
+          false
+        end
+      end
+
+      # Takes a block that returns [result, should_retry].
+      #
+      # Retries upto `retries_remaining` times, if `should_retry` is false or
+      # an exception is raised. `@backoff_policy` is used to determine the
+      # duration to sleep between attempts
+      #
+      # Returns [last_result, raised_exception]
+      def retry_with_backoff(retries_remaining, &block)
+        result, caught_exception = nil
+        should_retry = false
+
+        begin
+          result, should_retry = yield
+          return [result, nil] unless should_retry
+        rescue StandardError => e
+          should_retry = true
+          caught_exception = e
+        end
+
+        if should_retry && (retries_remaining > 1)
+          logger.debug("Retrying request, #{retries_remaining} retries left")
+          sleep(@backoff_policy.next_interval.to_f / 1000)
+          retry_with_backoff(retries_remaining - 1, &block)
+        else
+          [result, caught_exception]
+        end
+      end
+
+      # Sends a request for the batch, returns [status_code, body]
+      def send_request(write_key, batch)
+        payload = JSON.generate(
+          :sentAt => datetime_in_iso8601(Time.now),
+          :batch => batch
+        )
+        request = Net::HTTP::Post.new(@path, @headers)
+        request.basic_auth(write_key, nil)
+
+        if self.class.stub
+          logger.debug "stubbed request to #{@path}: " \
+            "write key = #{write_key}, batch = JSON.generate(#{batch})"
+
+          [200, '{}']
+        else
+          response = @http.request(request, payload)
+          [response.code.to_i, response.body]
+        end
+      end
+
+      class << self
+        attr_writer :stub
+
+        def stub
+          @stub || ENV['STUB']
+        end
+      end
+    end
+  end
+end

data/lib/clearbit/analytics/response.rb

@@ -0,0 +1,15 @@
+module Clearbit
+  class Analytics
+    class Response
+      attr_reader :status, :error
+
+      # public: Simple class to wrap responses from the API
+      #
+      #
+      def initialize(status = 200, error = nil)
+        @status = status
+        @error  = error
+      end
+    end
+  end
+end

data/lib/clearbit/analytics/utils.rb

@@ -0,0 +1,91 @@
+require 'securerandom'
+
+module Clearbit
+  class Analytics
+    module Utils
+      extend self
+
+      # public: Return a new hash with keys converted from strings to symbols
+      #
+      def symbolize_keys(hash)
+        hash.each_with_object({}) do |(k, v), memo|
+          memo[k.to_sym] = v
+        end
+      end
+
+      # public: Convert hash keys from strings to symbols in place
+      #
+      def symbolize_keys!(hash)
+        hash.replace symbolize_keys hash
+      end
+
+      # public: Return a new hash with keys as strings
+      #
+      def stringify_keys(hash)
+        hash.each_with_object({}) do |(k, v), memo|
+          memo[k.to_s] = v
+        end
+      end
+
+      # public: Returns a new hash with all the date values in the into iso8601
+      #         strings
+      #
+      def isoify_dates(hash)
+        hash.each_with_object({}) do |(k, v), memo|
+          memo[k] = datetime_in_iso8601(v)
+        end
+      end
+
+      # public: Converts all the date values in the into iso8601 strings in place
+      #
+      def isoify_dates!(hash)
+        hash.replace isoify_dates hash
+      end
+
+      # public: Returns a uid string
+      #
+      def uid
+        arr = SecureRandom.random_bytes(16).unpack('NnnnnN')
+        arr[2] = (arr[2] & 0x0fff) | 0x4000
+        arr[3] = (arr[3] & 0x3fff) | 0x8000
+        '%08x-%04x-%04x-%04x-%04x%08x' % arr
+      end
+
+      def datetime_in_iso8601(datetime)
+        case datetime
+        when Time
+          time_in_iso8601 datetime
+        when DateTime
+          time_in_iso8601 datetime.to_time
+        when Date
+          date_in_iso8601 datetime
+        else
+          datetime
+        end
+      end
+
+      def time_in_iso8601(time, fraction_digits = 3)
+        fraction = if fraction_digits > 0
+                     ('.%06i' % time.usec)[0, fraction_digits + 1]
+                   end
+
+        "#{time.strftime('%Y-%m-%dT%H:%M:%S')}#{fraction}#{formatted_offset(time, true, 'Z')}"
+      end
+
+      def date_in_iso8601(date)
+        date.strftime('%F')
+      end
+
+      def formatted_offset(time, colon = true, alternate_utc_string = nil)
+        time.utc? && alternate_utc_string || seconds_to_utc_offset(time.utc_offset, colon)
+      end
+
+      def seconds_to_utc_offset(seconds, colon = true)
+        (colon ? UTC_OFFSET_WITH_COLON : UTC_OFFSET_WITHOUT_COLON) % [(seconds < 0 ? '-' : '+'), (seconds.abs / 3600), ((seconds.abs % 3600) / 60)]
+      end
+
+      UTC_OFFSET_WITH_COLON = '%s%02d:%02d'
+      UTC_OFFSET_WITHOUT_COLON = UTC_OFFSET_WITH_COLON.sub(':', '')
+    end
+  end
+end

data/lib/clearbit/analytics/worker.rb

@@ -0,0 +1,66 @@
+require 'clearbit/analytics/defaults'
+require 'clearbit/analytics/message_batch'
+require 'clearbit/analytics/request'
+require 'clearbit/analytics/utils'
+
+module Clearbit
+  class Analytics
+    class Worker
+      include Clearbit::Analytics::Utils
+      include Clearbit::Analytics::Defaults
+      include Clearbit::Analytics::Logging
+
+      # public: Creates a new worker
+      #
+      # The worker continuously takes messages off the queue
+      # and makes requests to the segment.io api
+      #
+      # queue   - Queue synchronized between client and worker
+      # write_key  - String of the project's Write key
+      # options - Hash of worker options
+      #           batch_size - Fixnum of how many items to send in a batch
+      #           on_error   - Proc of what to do on an error
+      #
+      def initialize(queue, write_key, options = {})
+        symbolize_keys! options
+        @queue = queue
+        @write_key = write_key
+        @on_error = options[:on_error] || proc { |status, error| }
+        batch_size = options[:batch_size] || Defaults::MessageBatch::MAX_SIZE
+        @batch = MessageBatch.new(batch_size)
+        @lock = Mutex.new
+      end
+
+      # public: Continuously runs the loop to check for new events
+      #
+      def run
+        until Thread.current[:should_exit]
+          return if @queue.empty?
+
+          @lock.synchronize do
+            consume_message_from_queue! until @batch.full? || @queue.empty?
+          end
+
+          res = Request.new.post @write_key, @batch
+          @on_error.call(res.status, res.error) unless res.status == 200
+
+          @lock.synchronize { @batch.clear }
+        end
+      end
+
+      # public: Check whether we have outstanding requests.
+      #
+      def is_requesting?
+        @lock.synchronize { !@batch.empty? }
+      end
+
+      private
+
+      def consume_message_from_queue!
+        @batch << @queue.pop
+      rescue MessageBatch::JSONGenerationError => e
+        @on_error.call(-1, e.to_s)
+      end
+    end
+  end
+end

data/lib/clearbit/audiences.rb

@@ -0,0 +1,14 @@
+module Clearbit
+  class Audiences < Base
+    endpoint 'https://audiences.clearbit.com'
+    path '/v1/audiences'
+
+    def self.add_email(values = {})
+      post('email', values)
+    end
+
+    def self.add_domain(values = {})
+      post('domain', values)
+    end
+  end
+end

data/lib/clearbit/version.rb

@@ -1,3 +1,3 @@
 module Clearbit
-  VERSION = '0.2.8'
+  VERSION = '0.3.0'
 end

data/spec/lib/clearbit/analytics_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+require 'base64'
+
+describe Clearbit::Analytics do
+  before do |example|
+    Clearbit.key = 'clearbit_key'
+  end
+
+  it 'sends an identify request to Clearbit X' do
+    basic_auth = Base64.encode64('clearbit_key:').strip
+    x_stub = stub_request(:post, 'https://x.clearbit.com/v1/import').
+      with(
+        headers: { 'Authorization' => "Basic #{basic_auth}" }
+      ).to_return(status: 200, body: {success: true}.to_json)
+
+    Clearbit::Analytics.identify(
+      user_id: '123',
+      traits: {
+        email: 'david@clearbit.com',
+      },
+    )
+
+    expect(x_stub).to have_been_requested
+  end
+end

data/spec/lib/clearbit/prospector_spec.rb

@@ -6,8 +6,8 @@ describe Clearbit::Prospector do
   end
 
   context 'Prospector API' do
-    it 'should call out to the Prospector API' do
-      body  = []
+    it 'calls the Prospector API' do
+      body = { page: 1, page_size: 5, total: 723, results: [] }
 
       stub_request(:get, "https://prospector.clearbit.com/v1/people/search?domain=stripe.com").
         with(:headers => {'Authorization'=>'Bearer clearbit_key'}).
@@ -15,5 +15,15 @@ describe Clearbit::Prospector do
 
       Clearbit::Prospector.search(domain: 'stripe.com')
     end
+
+    it 'can page through records' do
+      body = { page: 2, page_size: 10, total: 12, results: [] }
+
+      stub_request(:get, "https://prospector.clearbit.com/v1/people/search?domain=stripe.com&page=2&page_size=10").
+        with(:headers => {'Authorization'=>'Bearer clearbit_key'}).
+        to_return(:status => 200, :body => body.to_json, headers: {'Content-Type' => 'application/json'})
+
+      Clearbit::Prospector.search(domain: 'stripe.com', page: 2, page_size: 10)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clearbit
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.3.0
 platform: ruby
 authors:
 - Alex MacCaw
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-24 00:00:00.000000000 Z
+date: 2019-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -129,6 +129,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/CODEOWNERS"
 - ".gitignore"
 - Gemfile
 - LICENSE
@@ -148,6 +149,19 @@ files:
 - examples/version.rb
 - examples/watchlist.rb
 - lib/clearbit.rb
+- lib/clearbit/analytics.rb
+- lib/clearbit/analytics/LICENSE
+- lib/clearbit/analytics/backoff_policy.rb
+- lib/clearbit/analytics/client.rb
+- lib/clearbit/analytics/defaults.rb
+- lib/clearbit/analytics/field_parser.rb
+- lib/clearbit/analytics/logging.rb
+- lib/clearbit/analytics/message_batch.rb
+- lib/clearbit/analytics/request.rb
+- lib/clearbit/analytics/response.rb
+- lib/clearbit/analytics/utils.rb
+- lib/clearbit/analytics/worker.rb
+- lib/clearbit/audiences.rb
 - lib/clearbit/autocomplete.rb
 - lib/clearbit/base.rb
 - lib/clearbit/discovery.rb
@@ -168,6 +182,7 @@ files:
 - lib/clearbit/version.rb
 - lib/clearbit/watchlist.rb
 - lib/clearbit/webhook.rb
+- spec/lib/clearbit/analytics_spec.rb
 - spec/lib/clearbit/discovery_spec.rb
 - spec/lib/clearbit/enrichment_spec.rb
 - spec/lib/clearbit/logo_spec.rb
@@ -195,11 +210,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
 summary: API client for clearbit.com
 test_files:
+- spec/lib/clearbit/analytics_spec.rb
 - spec/lib/clearbit/discovery_spec.rb
 - spec/lib/clearbit/enrichment_spec.rb
 - spec/lib/clearbit/logo_spec.rb