enrich-api 1.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 37f45990f1be5bce18af3ddf71d80511a5ed49e4
+  data.tar.gz: 54401a9dc12c152106112931515d60b819264ad4
+SHA512:
+  metadata.gz: 5953fe739691b0e09c7e29202d22efa55f059cfdad942e92fe37ec169e1087ccfc172126fc7a739d978fef75757a5372872c1a1cfe2f6042f1e8ed2ea66ecd3f
+  data.tar.gz: d92dfa40089fba33c72c28c3c4002f2f0b7fe8acb39776dc902effaa0459d21a27fdc6f146eb47818d6393427dc7f86f6f4089703f3ae4b8e2beb0b327387088

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+*.rbc
+
+/.bundle/
+/vendor/
+
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gem "rest-client"

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2017 Enrich
+
+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

@@ -0,0 +1,100 @@
+# enrich-api-ruby
+
+The Enrich API Ruby wrapper. Enrich, Search and Verify data from your Ruby services.
+
+Copyright 2017 Enrich. See LICENSE for copying information.
+
+* **📝 Implements**: [Enrich REST API ~ v1](https://docs.enrichdata.com/api/v1/) at reference revision: 07/24/2017
+* **😘 Maintainer**: [@valeriansaliou](https://github.com/valeriansaliou)
+
+## Usage
+
+Add the library to your `Gemfile`:
+
+```bash
+gem 'enrich-api', '~> 1.0'
+```
+
+Then, import it:
+
+```ruby
+require 'enrich-api'
+```
+
+Construct a new authenticated Enrich client with your `user_id` and `secret_key` tokens (you can generate those from your Enrich Dashboard, [see the docs](https://docs.enrichdata.com/api/v1/)).
+
+```ruby
+client = Enrich::Client.new
+
+client.authenticate("ui_xxxxxx", "sk_xxxxxx")
+```
+
+Then, consume the client eg. to enrich an email address:
+
+```ruby
+data = client.enrich.person({
+  email: "valerian@crisp.chat"
+})
+```
+
+## Authentication
+
+To authenticate against the API, generate your tokens (`user_id` and `secret_key`) **once** from your [Enrich Dashboard](https://dashboard.enrichdata.com/).
+
+Then, pass those tokens **once** when you instanciate the Enrich client as following:
+
+```ruby
+# Make sure to replace 'user_id' and 'secret_key' with your tokens
+client.authenticate("user_id", "secret_key")
+```
+
+## Data Discovery
+
+**When Enrich doesn't know about a given data point, eg. an email that was never enriched before, it launches a discovery. Discoveries can take a few seconds, and sometimes more than 10 seconds.**
+
+This library implements a retry logic with a timeout if the discovery takes too long, or if the item wasn't found.
+
+Thus, you can expect some requests, especially the Enrich requests, to take more time than expected. This is normal, and is not a performance issue on your side, or on our side. Under the hood, when you request a data point (eg. enrich a person given an email) that doesn't yet exist in our databases, the Enrich API returns the HTTP response `201 Created`. Then, this library will poll the enrich resource for results, with intervals of a few seconds. The API will return `404 Not Found` as the discovery is still processing and no result is yet known at this point. Once a result is found, the API will reply with `200 OK` and return discovered data. If the discovery fails and no data can be aggregated for this email, the library aborts the retry after some time (less than 20 seconds), and returns a `not_found` error.
+
+If a requested data point is already known by the Enrich API, it will be immediately returned, which won't induce any delay.
+
+## Resource Methods
+
+This library implements all methods the Enrich API provides. See the [API docs](https://docs.enrichdata.com/api/v1/) for a reference of available methods, as well as how returned data is formatted.
+
+### Verify API
+
+#### Validate an Email
+
+* **Method:** `client.verify.validate_email(query)`
+* **Docs:** [https://docs.enrichdata.com/api/v1/#validate-an-email](https://docs.enrichdata.com/api/v1/#validate-an-email)
+
+```ruby
+data = client.verify.validate_email({
+  email: "valerian@crisp.chat"
+})
+```
+
+### Enrich API
+
+#### Enrich a Person
+
+* **Method:** `client.enrich.person(query)`
+* **Docs:** [https://docs.enrichdata.com/api/v1/#enrich-a-person](https://docs.enrichdata.com/api/v1/#enrich-a-person)
+
+```ruby
+data = client.enrich.person({
+  email: "valerian@crisp.chat"
+})
+```
+
+#### Enrich a Network
+
+* **Method:** `client.enrich.network(query)`
+* **Docs:** [https://docs.enrichdata.com/api/v1/#enrich-a-network](https://docs.enrichdata.com/api/v1/#enrich-a-network)
+
+```ruby
+data = client.enrich.network({
+  ip: "178.62.89.169"
+})
+```

data/enrich-api.gemspec

@@ -0,0 +1,15 @@
+Gem::Specification.new do |s|
+  s.name          = 'enrich-api'
+  s.version       = '1.1.3'
+  s.date          = Date.today
+  s.summary       = "Enrich API Ruby"
+  s.description   = "Enrich API Ruby"
+  s.authors       = ["Valerian Saliou"]
+  s.email         = 'valerian@valeriansaliou.name'
+  s.files         = `git ls-files`.split($/)
+  s.homepage      = 'https://enrichdata.com'
+  s.license       = 'MIT'
+  s.require_paths = ['lib']
+
+  s.add_dependency 'rest-client', '~> 2.0.0'
+end

data/examples/enrich_network.rb

@@ -0,0 +1,21 @@
+##
+# enrich-api-ruby
+#
+# Copyright 2017, Valerian Saliou
+# Author: Valerian Saliou <valerian@valeriansaliou.name>
+##
+
+require 'enrich-api'
+
+client = Enrich::Client.new
+
+client.authenticate(
+  "ui_a311da78-6b89-459c-8028-b331efab20d5",
+  "sk_f293d44f-675d-4cb1-9c78-52b8a9af0df2"
+)
+
+data = client.enrich.network({
+  ip: "178.62.89.169"
+})
+
+puts data.inspect

data/examples/enrich_person.rb

@@ -0,0 +1,21 @@
+##
+# enrich-api-ruby
+#
+# Copyright 2017, Valerian Saliou
+# Author: Valerian Saliou <valerian@valeriansaliou.name>
+##
+
+require 'enrich-api'
+
+client = Enrich::Client.new
+
+client.authenticate(
+  "ui_a311da78-6b89-459c-8028-b331efab20d5",
+  "sk_f293d44f-675d-4cb1-9c78-52b8a9af0df2"
+)
+
+data = client.enrich.person({
+  email: "valerian@crisp.chat"
+})
+
+puts data.inspect

data/examples/verify_validate_email.rb

@@ -0,0 +1,21 @@
+##
+# enrich-api-ruby
+#
+# Copyright 2017, Valerian Saliou
+# Author: Valerian Saliou <valerian@valeriansaliou.name>
+##
+
+require 'enrich-api'
+
+client = Enrich::Client.new
+
+client.authenticate(
+  "ui_a311da78-6b89-459c-8028-b331efab20d5",
+  "sk_f293d44f-675d-4cb1-9c78-52b8a9af0df2"
+)
+
+data = client.verify.validate_email({
+  email: "valerian@crisp.chat"
+})
+
+puts data.inspect

data/lib/enrich.rb

@@ -0,0 +1,113 @@
+##
+# enrich-api-ruby
+#
+# Copyright 2017, Valerian Saliou
+# Author: Valerian Saliou <valerian@valeriansaliou.name>
+##
+
+require 'rest-client'
+require 'json'
+
+require_relative 'resources/enrich'
+require_relative 'resources/verify'
+
+module Enrich
+  class Client
+    attr_writer :rest_host
+    attr_writer :rest_base_path
+
+    attr_accessor :enrich
+    attr_accessor :verify
+
+    @@created_status_code = 201
+    @@not_found_status_code = 404
+    @@created_retry_count_max = 2
+
+    def initialize()
+      @auth = {}
+
+      @enrich = Enrich::EnrichResource.new(self)
+      @verify = Enrich::VerifyResource.new(self)
+    end
+
+    public
+
+    def authenticate(user_id, secret_key)
+      @auth["user_id"] = user_id
+      @auth["secret_key"] = secret_key
+    end
+
+    def rest_host
+      @rest_host || "https://api.enrichdata.com"
+    end
+
+    def rest_base_path
+      @rest_base_path || "/v1"
+    end
+
+    def timeout
+      @timeout || 5
+    end
+
+    def _get(resource, query)
+      self._do_get(resource, query, 0, 0)
+    end
+
+    protected
+
+    def _do_get(resource, query, retry_count, hold_for_seconds)
+      # Abort?
+      if retry_count > @@created_retry_count_max
+        raise RestClient::NotFound
+      else
+        # Hold.
+        sleep hold_for_seconds
+
+        begin
+          response = RestClient::Request.execute(
+            :url => self._prepare_rest_url(resource),
+            :method => :get,
+            :timeout => self.timeout,
+
+            :user => @auth["user_id"],
+            :password => @auth["secret_key"],
+
+            :headers => {
+              :user_agent => "enrich-api-ruby/1.1.3",
+              :accept => :json,
+              :content_type => :json,
+              :params => query
+            }
+          )
+
+          status = response.code
+        rescue RestClient::NotFound
+          status = @@not_found_status_code
+        end
+
+        # Re-schedule request? (created)
+        if status == @@created_status_code || (retry_count > 0 &&
+            status == @@not_found_status_code)
+          if response && response.headers[:retry_after]
+            hold_for_seconds = Integer(response.headers[:retry_after])
+          end
+
+          return self._do_get(
+            resource, query, retry_count + 1, hold_for_seconds
+          )
+        end
+
+        # Not found?
+        if status == @@not_found_status_code
+          raise RestClient::NotFound
+        end
+
+        return JSON.parse(response)
+      end
+    end
+
+    def _prepare_rest_url(resource)
+      return self.rest_host + self.rest_base_path + resource
+    end
+  end
+end

data/lib/resources/enrich.rb

@@ -0,0 +1,24 @@
+##
+# enrich-api-ruby
+#
+# Copyright 2017, Valerian Saliou
+# Author: Valerian Saliou <valerian@valeriansaliou.name>
+##
+
+require 'rest-client'
+
+module Enrich
+  class EnrichResource
+    def initialize(parent)
+      @parent = parent
+    end
+
+    def person(query)
+      return @parent._get("/enrich/person", query)
+    end
+
+    def network(query)
+      return @parent._get("/enrich/network", query)
+    end
+  end
+end

data/lib/resources/verify.rb

@@ -0,0 +1,20 @@
+##
+# enrich-api-ruby
+#
+# Copyright 2017, Valerian Saliou
+# Author: Valerian Saliou <valerian@valeriansaliou.name>
+##
+
+require 'rest-client'
+
+module Enrich
+  class VerifyResource
+    def initialize(parent)
+      @parent = parent
+    end
+
+    def validate_email(query)
+      return @parent._get("/verify/validate/email", query)
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: enrich-api
+version: !ruby/object:Gem::Version
+  version: 1.1.3
+platform: ruby
+authors:
+- Valerian Saliou
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-02-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+description: Enrich API Ruby
+email: valerian@valeriansaliou.name
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- enrich-api.gemspec
+- examples/enrich_network.rb
+- examples/enrich_person.rb
+- examples/verify_validate_email.rb
+- lib/enrich.rb
+- lib/resources/enrich.rb
+- lib/resources/verify.rb
+homepage: https://enrichdata.com
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: Enrich API Ruby
+test_files: []