clearbit 0.2.7 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c2fab0d003e3376ebff21752d59afaa593aaeb87
-  data.tar.gz: bb8c58beafdec8b4630bb88e9edf73901175a44e
+SHA256:
+  metadata.gz: 775ec8d65111d426a0ec0424135c0f070c3d9e6834f818dfb902650f761836f3
+  data.tar.gz: 0c8cd65375787f5df66bc3821ac154bcac21d649b6e97e8804953ae4255463a1
 SHA512:
-  metadata.gz: b8dc286b83eac1dcd4f76fa5b4949aad3fa15f45c4df635055ca85a46b81ef78b01bfc4b4d1f831368cc1e1011689637baf3d2254039e46d387310ade7f223de
-  data.tar.gz: 56d2b80cfed16e25ee0c78aaaf3dc1762f16ca33f9a871dfaee10731c07a5d11542b72ae3817f44e4935eb2b6fffc16101de757a51d7985697a8c3cfef172218
+  metadata.gz: 24fe794b5ed903da7d941fffbbdfe0fbd956bb7aabdb7bb2d2d66d412892d01b1ab551de7c28f48d72f66a04a1772d2ba7edfad2eb3c58fd5007874087851a86
+  data.tar.gz: bad29a9ca346fd5accb3441bc1c9bc3272830bb2c15c5c5bc14198c68608100aca97dc7725a7a1d150e8b1066f767404ca575fbc860beae6ec3202edb53e247e

data/.github/CODEOWNERS

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

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+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
+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/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,52 @@ 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
+
+*NOTE:* We **strongly** recommend using `clearbit.js` for Analytics and integrating with Clearbit X. It handles a lot of complexity, like generating `anonymous_id`s and associating them with `user_id`s when a user is identified. It also automatically tracks `page` views with the full data set.
+
+### Identifying Users
+
+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 if no anonymous_id is sent. The user's ID in your database.
+  anonymous_id: session[:anonymous_id], # Required if no user_id is sent. A UUID to track anonymous users.
+  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 analytical traits can also be sent, like the plan a user is on etc
+  },
+  context: {
+    ip: '89.102.33.1' # Optional, but strongly recommended when identifying users
+  }                   # as they sign up, or log in
+)
+```
+
+### Page Views
+
+Use the `page` method, and send the users `anonymous_id` along with the `url` they're viewing, and the `ip` the request comes from in order to create Companies inside of Clearbit X and track their page views.
+
+```ruby
+Clearbit::Analytics.page(
+  user_id: '1234', # Required if no anonymous_id is sent. The user's ID in your database.
+  anonymous_id: session[:anonymous_id], # Required if no user_id is sent. A UUID to track anonymous users.
+  name: 'Clearbit Ruby Library', # Optional, but strongly recommended
+  properties: {
+    url: 'https://github.com/clearbit/clearbit-ruby?utm_source=google', # Required. Likely to be request.referer
+    path: '/clearbit/clearbit-ruby', # Optional, but strongly recommended
+    search: '?utm_source=google', # Optional, but strongly recommended
+    referrer: nil, # Optional. Unlikely to be request.referrer.
+  },
+  context: {
+    ip: '89.102.33.1', # Optional, but strongly recommended.
+  },
+)
+```
+
 ## 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 +135,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 +149,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/name_domain.rb

@@ -0,0 +1,4 @@
+require 'clearbit'
+require 'pp'
+
+pp Clearbit::NameDomain.find(name: 'Stripe')

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/examples/reveal.rb

@@ -0,0 +1,11 @@
+require 'clearbit'
+require 'csv'
+
+puts 'domain,fuzzy'
+
+STDIN.read.each_line do |line|
+  result = Clearbit::Reveal.find(ip: line.strip)
+  next puts unless result
+  puts CSV.generate_line([result.domain, result.fuzzy])
+end
+

data/examples/risk.rb

@@ -0,0 +1,13 @@
+require 'clearbit'
+
+# Step 1)
+# Add the JS library + load it
+# https://clearbit.com/docs#risk-api-javascript-library
+
+# Step 2)
+result = Clearbit::Risk.calculate(
+  email: 'test@example.com',
+  ip:    '0.0.0.0'
+)
+
+p result

data/examples/risk_flag.rb

@@ -0,0 +1,35 @@
+require 'clearbit'
+require 'pp'
+require 'optparse'
+
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: risk_flag.rb [options]"
+
+  opts.on("-iIP", "--ip=IP", "IP address") do |ip|
+    options[:ip] = ip
+  end
+
+  opts.on("-eEMAIL", "--email=EMAIL", "Email address") do |email|
+    options[:email] = email
+  end
+
+  opts.on("-tTYPE", "--type=TYPE", "Type") do |type|
+    options[:type] = type
+  end
+
+  opts.on("-h", "--help", "Prints this help") do
+    puts opts
+    exit
+  end
+end.parse!
+
+options[:type] ||= 'spam'
+
+begin
+  Clearbit::Risk.flag(options)
+rescue Nestful::Error => err
+  pp err.decoded
+else
+  puts 'Successfully flagged!'
+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,12 +19,14 @@ module Clearbit
     key || raise('Clearbit.key not set')
   end
 
+  autoload :Audiences, 'clearbit/audiences'
   autoload :Autocomplete, 'clearbit/autocomplete'
   autoload :Base, 'clearbit/base'
-  autoload :Enrichment, 'clearbit/enrichment'
   autoload :Discovery, 'clearbit/discovery'
+  autoload :Enrichment, 'clearbit/enrichment'
   autoload :Logo, 'clearbit/logo'
   autoload :Mash, 'clearbit/mash'
+  autoload :NameDomain, 'clearbit/name_domain'
   autoload :Pending, 'clearbit/pending'
   autoload :Prospector, 'clearbit/prospector'
   autoload :Resource, 'clearbit/resource'

data/lib/clearbit/analytics.rb

@@ -0,0 +1,62 @@
+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
+
+    # Proxy page through to a client instance, in order to keep the client
+    # consistent with how the other Clearbit APIs are accessed
+    def self.page(args)
+      analytics = new(write_key: Clearbit.key)
+      analytics.page(args)
+      analytics.flush
+    end
+
+    # Proxy group through to a client instance, in order to keep the client
+    # consistent with how the other Clearbit APIs are accessed
+    def self.group(args)
+      analytics = new(write_key: Clearbit.key)
+      analytics.group(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/README.md

@@ -0,0 +1,114 @@
+# Getting Started with Clearbit::Analytics
+
+## Initialization
+
+Make sure you set your `Clearbit.key` as part of your apps initialization, or before you make use of `Clearbit::Analytics`. You can find your secret key at [https://dashboard.clearbit.com/api](https://dashboard.clearbit.com/api)
+
+`Clearbit.key = 'sk_…'`.
+
+We also recommend ensuring that every person has a randomly generated `anonymous_id` to aid tracking page events and assist in matching up anonymous traffic to signed in users.
+
+```ruby
+class ApplicationController
+  before_action :set_anonymous_id
+  …
+
+  def set_anonymous_id
+    session[:anonymous_id] ||= SecureRandom.uuid
+  end
+
+  …
+end
+```
+
+## Importing Users into X
+
+You'll want to loop through your users, and call `.identify` for each one, passing the users `id`, and their `email` along with any other traits you value.
+
+```ruby
+User.find_in_batches do |users|
+  users.each do |user|
+    Clearbit::Analytics.identify(
+      user_id: user.id, # Required.
+      traits: {
+        email: user.email, # Required.
+        company_domain: user.domain || user.email.split('@').last,  # Optional, strongly recommended.
+        first_name: user.first_name,  # Optional.
+        last_name: user.last_name, # Optional.
+        # … other analytical traits can also be sent, like the plan a user is on etc.
+      },
+    )
+  end
+end
+```
+
+## Identifying Users on sign up / log in
+
+Identifying users on sign up, or on log in will help Clearbit X associate the user with anonymous page views.
+
+```ruby
+class SessionsController
+  …
+
+  def create
+    …
+
+    identify(current_user)
+
+    …
+  end
+
+  private
+
+  def identify(user)
+    Clearbit::Analytics.identify(
+      user_id: user.id, # Required
+      anonymous_id: session[:anonymous_id], # Optional, strongly recommended. Helps Clearbit X associate with anonymous visits.
+      traits: {
+        email: user.email, # Required.
+        company_domain: user.domain || user.email.split('@').last,  # Optional, strongly recommended.
+        first_name: user.first_name,  # Optional.
+        last_name: user.last_name, # Optional.
+        # … other analytical traits can also be sent, like the plan a user is on etc.
+      },
+      context: {
+        ip: request.ip, # Optional, but strongly recommended. Helps Clearbit X associate with anonymous visits.
+      },
+    )
+  end
+
+  …
+end
+```
+
+## Sending Page views
+
+Tracking page views is best done using a `anonymous_id` you generate for each user. You'll need to sent the `url` as part of the `properties` hash, and the `ip` as part of the `context` hash. Any other data you can provide will greatly help with segmentation inside of Clearbit X.
+
+
+```ruby
+uri = URI(request.referer) # You'll likely want to do some error handling here.
+
+Clearbit::Analytics.page(
+  user_id: current_user&.id, # Optional
+  anonymous_id: session[:anonymous_id], # Required
+  properties: {
+    url: request.referrer, # Required. Because this is a backend integration, the referrer is the URL that was visited.
+    path: format_path(uri.path), # Optional, but strongly recommended.
+    search: format_search(uri.params), # Optional, but strongly recommended.
+    referrer: nil, # Optional. Not the `request.referer`, but the referrer of the original page view.
+  },
+  context: {
+    ip: request.ip, # Required. Helps Clearbit X associate anonymous visits with Companies.
+  },
+)
+
+def format_path(path)
+  path.presence || '/'
+end
+
+def format_search(search)
+  return unless search
+  '?' + search
+end
+```